1 - API
This chapter defines the API functionality and messages.
1.1 - Summary
This defines the XFS4IoT API including but not limited to:
* Service Discovery
* Message Definition
* End to End Security
1.2 - General Information
1.2.1 - Service Discovery
This section covers the process for discovering services before they can be used.
1.2.1.1 - Introduction
Multiple services can be supplied by multiple vendors. This standard doesn't require coordination between these different organization, or between the service publishers and the service client. It is possible to operate a system with components from multiple hardware vendors, and with third party clients, without the prior knowledge of any party.
This specification covers an environment using WebSockets to communicate between services and clients, either on a single machine or across a network.
This section covers both the process for publishing a service such that it can be discovered, and the discovery process used by the service client.
There is also a clear definition of responsibility for each component, including when there are dependencies between components. There are no shared components required to coordinate the system.
The underlying network can use any protocol that supports WebSockets such as IPv4 or IPv6. Nothing in this document requires any particular underlying protocol.
This document uses CAN, WILL, MUST, SHOULD etc. in the normal ways to distinguish between requirements, recommendations, permissions and possibilities.
Requirements of this spec will be formatted as follows:
This is an example requirement
All other text is commentary used to illustrate the reasoning of the requirements. Where there is any conflict the requirement text always takes priority.
1.2.1.2 - Overview
In this standard there are two types of "end-point"; publisher and service. Each end-point, of either type, is published by a single software/hardware vendor. A publisher end-point is used for service discovery, to discover service end-points. A single service end-point can expose multiple "services", where each service typically represents a single piece of hardware. A single machine (or a single IP address) may expose multiple publisher and service end-points from different vendors. A "client" application may consume multiple services from multiple service end-points on the same machine, or across multiple machines.
On startup of the machine, any software services attempt to claim access to individual network ports using the underlying operating system mechanism. Ports are claimed sequentially from a known sequence. Each port becomes an end-point that can publish multiple services from a single vendor.
A client application will attempt to connect to each port on a machine in the known sequence to get a list of all active publisher end-points. For each publisher end-point it then exchanges JSON messages across WebSockets with URIs using a known format to recover a list of services published by that end-point. Once it has a full list of services it can use WebSocket connections to communicate with each service to perform whichever actions are required.
1.2.1.3 - Machine Identification
Machines publishing services are identified by URIs. Machines exposing end-points can be identified by an IP address or by a DNS name.
Either the IP address or DNS name for a machine must be known by the client for the client to connect. This would probably be a configuration setting for the client and would need to be known by the organization setting up the client, but this configuration is outside the scope of this document.
1.2.1.4 - Network Protocol
TLS security will be used to secure network connections. The only exception will be when the network connection between the client and service can be physically secured because they are both inside the same cabinet. In that case it will be possible to use clear communication without TLS encryption.
The publisher will publish all WebSocket services protected by TLS encryption. This will be identified by the wss:// protocol specifier.
The publisher may publish WebSocket services without TLS encryption, as a clear WebSocket connection, but only if the physical connection between the service and the client is physically protected. It is up to the hardware manufaturer to ensure this physical protection is sufficient. This unsecured connection will be identified by the ws:// protocol specifier.
Where TLS is used, the service will be protected by a mutually trusted server side certificate as part of the TLS protocol. This complete certificate chain must be mutually trusted by the client and service.
Establishing and managing the certificates between the service and the client is outside of the scope of this spec but trust must be in place. This might be achieved using a public third party certificate authority that issues TLS certificates. Alternatively it might be achieved using a bank's own internal CA. It shouldn't depend on a private CA or certificates issued by a vendor, which might limit access to the service.
A WSS connections with invalid certificates will be invalid and will be rejected by both the client and the service.
1.2.1.5 - URI Format
Communications are defined by URI's
Communication with service publishers and services will be through distinct URIs which will use the following format
wss://machinename:portnumber/xfs4iot/v1.0/servicename
This consists of the following parts:
wss:// or ws://
The protocol id for secure WebSockets. This should be wss:// for secure connections. An insecure ws:// connection can be
used when the connection is physically secured, inside an ATM enclosure.
machinename
The identification of the machine publishing end-points. This can be an IP address or DNS name.
portnumber
The port number discovered through the initial service discovery process
XFS4IoT
A literal string. The inclusion of this part identifies standard XFS4IoT services published on this URI. It allows the
possibility of a single vendor publishing standard and non-standard proprietary services on the same port. Any standard
service URI will start with this string. Any non-standard service's URI must not start with this string.
v1.0
The version of the XFS4IoT specification being used by this service. This will be updated in future versions of the
specification and allows support for multiple versions of the specification on the same machine and end-point.
Note that most future changes to the XFS4IoT specification will be done in a non-breaking, backwards and forwards compatible way. For example, optional fields will be added to JSON messages when required. This means that changes to the version field of the URI will be very rare. It will only be changed if there is a breaking, incompatible change or a fundamental change to the API. Because of this there won't be any need for complex version negotiation between the client and the service. The client will simply attempt to open the version of the API that it supports.
ServiceName
This will be included in the URI to allow different services to be identified on the same port. Services will normally
match individual devices. The exact service name is discovered during service discovery and is vendor dependent. The
format of the service name shouldn't be assumed. The only URI that doesn't include a service name is the service
discovery URI.
For example, a service discovery URI might be;
- wss://terminal321.atmnetwork.corporatenet:443/xfs4iot/v1.0
- wss://192.168.21.43:5848/xfs4iot/v1.0
Service URI might be;
- wss://terminal321.atmnetwork.corporatenet:443/xfs4iot/v1.0/maincashdispenser
- wss://192.168.21.43:5848/xfs4iot/v1.0/cardreader1
The URI will be case sensitive. The URI will be lower case.
1.2.1.6 - Service Publishing
Service publishers will negotiate access to resources and publish services using the following process.
Port Sequence
Services will be published on a sequence of IP ports consisting of two ranges consisting of the port 80 and 443 followed by the ports 5846 to 5856 (inclusive.) Hence the full sequence of ports will be 12 ports as,
80 or 443, 5846, 5847, 5848, ... 5855, 5856
Port 80 will only be used with HTTP/WS. Port 443 will only be used with HTTPS/WSS. All other ports may be used with either or both HTTP/WS and HTTPS/WSS.
Port 80 and 443 are the standard ports for HTTP and HTTPS and have the advantage that they are likely to be open on firewalls. The correct port will be used to match the protocol - 80 for HTTP/WS and 443 for HTTPS/WSS. Other ports are flexible and can be used for either protocol by the Service Publisher.
The port range 5846-5856 is semi-randomly selected in the 'user' range of the port space as defined by ICANN/IANA. This range is currently unassigned by IANA.
Free End-point Port Discovery
On startup each service publisher must attempt to connect to the first port in the port sequence. It will use the underlying OS and network stack to attempt to bind to this port.
All network access must go through the normal underlying OS mechanism. One service publisher must not block another publisher from accessing the network.
If the underlying OS reports that the port is already in use the service publisher will repeat the same process with the next port in the port sequence. This will be repeated until a port is successfully bound to, or all ports in the sequence have been tried.
If no available port can be found the service publisher will have failed to start. How this failure is handled by the service publisher is undefined.
It's important that a single organisation doesn't use up multiple ports, since this could lead to all the ports being blocked so that other publishers can't get a free port.
Any single organisation will publish all services on a single port, determined dynamically as above.
Note: A service publisher will only fail to find a free port if more than 12 different hardware vendors are attempting to publish services from the same machine. This should be unusual.
Handling Incoming Connections
Once a service publisher has successfully bound to a port it must handle connection attempts. It will accept all connections from any clients without filtering attempts. Security around connections will be handled after a connection has been established.
Note: This document does not cover restrictions on connections to services or managing permissions for connections, such as limiting connections to certain machines or sub-nets. This would normally be under the control of the machine deployer and can be controlled through normal firewall settings and network configuration.
Incoming connection attempts will specify a specific URI using the normal WebSocket process. The service publisher will allow connections to valid URIs as defined in this spec and track which URI each connection was made to.
The initial connection will be to the URI wss://machinename:port/xfs4iot/v1.0. This connection will then be used to list/discover individual services using the process outlined below (Service discovery).
1.2.1.7 - Client
A client application must be able to discover and open a connection to each service that it will use. It does this in two steps; firstly, through publisher end-point discovery, then through service discovery for each service end-point. It will do this through the following process.
Publisher End-point Discovery
The client will enumerate end-points by attempting to open a WebSocket connection to the following URL on each port in the port sequence. (See Port sequence).
wss://machinename:port/xfs4iot/v1.0
The client will continue to enumerate publisher end-points by repeating for each port number in the port sequence until all ports have been tried.
The client will also start service discovery on the open connection. There is no requirement for the order of opening ports and discovering services. All ports connections may be created first followed by service discover, or port enumeration and service discovery may continue in parallel.
If the connection attempt to any port fails then the application will attempt error handling for network issues, machine powered off etc. The details of error handling are left up to the application.
1.2.1.8 - Service Endpoint Discovery
Once a connection has been established between the client and each publisher end-point, the client will discover the services published by sending a service discovery command and receiving events in the usual way.
The only command sent to the publisher end-point will be "Common.GetServices".
{
"header": {
"type": "command",
"name": "Common.GetServices",
"requestId": "123"
},
"payload": {
}
}
The end-point will acknowledge the command in the normal way.
The command will be followed by zero or more events. The command will complete with a completion event, in the normal way. Each event, and the completion event will contain the following fields:
{
"header": {
"type": "completion",
"name": "Common.GetServices",
"requestId": "123"
},
"payload": {
"vendorName": "<Name of hardware/software vendor>",
"services": [
{
"serviceURI": "wss://machinename:port/xfs4iot/v1.0/<servicename1>"
},
{
"serviceURI": "wss://machinename:port/xfs4iot/v1.0/<servicename2>"
}
]
}
}
The service end-point URI will be returned as serviceURI.
A secure wss:// protocol URI will be returned whenever possible.
An insecure ws:// protocol URI may be returned instead. If an insecure ws:// protocol is used then the hardware vendor will be responsible for ensuring the security of the connection.
Much of the security of the XFS4IoT specification is based around TLS encryption. Using an unencrypted ws:// protocol will have a negative impact on that security, so as far as possible a wss:// should always be used.
If an unencrypted ws:// connection is used then alternative methods should be used to keep the connection secure, perhaps by physically securing the connection.
The Publisher service will send an event to report on every URI. A single event may report on one or more URI. URI will not be repeated between events, so each URI will be reported exactly once.
A publisher service may be designed to send one URI per event, or it may group URI together into a smaller number of events. The publisher should try and send events to report on each URI as soon as each URI is known. It's possible a publisher will know the complete set of URI when they're requested and can send them all at once in one or more events. Alternatively the URI may not be known straight away (such as if an IP address or port is being dynamically allocated.) In that case the publisher service would delay sending events for unknown URI until the full URI is known.
Having each URI reported at most once means that a client can connect to each URI reported in events without having to track which URI have already been connected to. This simplifies the client. Alternatively, a client may wait for the completion event and a full set of URI before attempting to connect. This would be simpler to implement, but might be slower to start up.
The completion event will contain every URI that the publisher service is aware of.
The publisher service will follow the above process to publish all URI that it's aware of. It will not suppress URI based on device status or service status.
For example, a device might be powered off, in the process of powering on, or powered on but have a hardware fault that makes it impossible to use. In all cases the publisher service will publish the URI anyway. The client can't assume anything about the device based on the URI. It will always need to query the service at the URI for its status to know more.
Events should be sent as soon as a URI is known by the publisher - the event doesn't mean or imply that the URI is currently available or can be connected to - that error handling must be performed by the client (see below.)
Note: Even if the publisher service could know that a URI was valid at the time that it sends the event, the client can't know that the URI is still valid when it attempts to use the URI. It could have failed between querying and connecting. So the client has to handle errors, timeouts and retrying when connecting to the URI.
The client may then attempt to open a WebSocket connection to each of the returned URI. The client will handle connection failures and timeouts by repeating the attempts to connect such that the service has a reasonable amount of time to start up.
Each service will endeavor to accept connections as quickly as possible during startup and restarts. Once a connection has been accepted a service may continue to report a 'starting' status until the device is physically started and ready.
Some devices are slow physically to start up, but software should be able to start relatively quickly. So, for example, a cash recycler device might be able to accept a connection within a few seconds of power being applied, but the physical hardware can take several minutes to reset. During this time the service would accept connections but report a 'starting' status.
Each connection will be used to communicate with a single service. The service will then be queried for details about that service, such as the type of service or device that it represents and the messages and interfaces that it supports. (todo: Querying for service information needs to be documented elsewhere.)
The connection to the service will be kept open for as long as the service is in use. Details of the service lifetime are covered elsewhere.
The returned URI is a full URI including the machine name and port. It is possible that these values will be different to the service discovery URI - each service may be on a different machine, a different IP address, and a different port. The port is also independent of the discovery port range. It can be any port number.
The service URI values will have the same version number as the service discovery URI version number. Different versions of the API will not be mixed.
If a client wants to open multiple different API version numbers then it should perform service discovery against each of the possible version URI strings.
The client may close the publisher connection once it has completed service discovery, or it may keep the connection open. This will have no effect on the behavior of services.
1.2.2 - Messages
Overview of the general message handling process for XFS4IoT.
1.2.2.1 - API Definition
In XFS4IoT Services are accessible through a WebSocket Interface. The following specification details the format of message sent to the XFS4IoT Service.
Data sent across the WebSocket stream utilize JSON as a format (https://www.json.org/). Each message conforms to one of the following Message Types. Message Types are documented in the following table.
| Message Type | Direction | Description |
|---|---|---|
| Command | Client to Service | Message sent to the XFS4IoT Service to perform a Command |
| Acknowledge | Service to Client | Message from the XFS4IoT Service indicating if the Command is valid and queued. |
| Event | Service to Client | Intermediate message from the XFS4IoT Service indicating progress of the Command. |
| Completion | Service to Client | Final message from the XFS4IoT Service indicating the Command is complete. |
| Unsolicited | Service to Client | Message from the XFS4IoT Service unrelated to a Command. |
All the message types follow the same JSON structure conforming of a mandatory header and payload.
- header : containing attributes that are common across all Message Types to allow the payload to be efficiently parsed
- payload : containing information that is specific to the Message Type and action.
Header and Payload are the only two attributes defined at the top level of the JSON structure as the example illustrated below.
{
"header": {
},
"payload": {
}
}
1.2.2.2 - Header Definition
Headers are consistent across all XFS4IoT Message Types. All of the following attributes are mandatory.
- "type", string : The message type. This must be one of "command", "acknowledge", "event", "completion" or "unsolicited"
- "name", string : The message name, for example "CardReader.Status"
- "requestId", int : Unique request identifier supplied by the client used to correlate the command with acknowledge, event and completion messages. For unsolicited messages the value will be zero. For all other message types this will be an integer. The client will supply values that are positive, incremental and start with 1, so that unsolicited events can be distinguished. The service will check that the requestID does not conflict with a currently executing or queued command request from the same client and reject if it does.
The following example illustrates the header for a CardReader.Status command Message.
{
"header": {
"type": "command",
"name": "CardReader.Status",
"requestId": 12345
},
"payload": {
}
}
1.2.2.3 - Payload Definition
The XFS4IoT interface specifications detail the payload content for the class command, event, completion and unsolicited messages.
1.2.2.4 - Extra Fields
Since the XFS4IOT message format it JSON it is possible to include extra values not defined by the specification. This can be useful in some cases and is allowed as long as those extra values don't impact the proper functioning of the service or client.
For example, it may be useful to include fields with extra debugging information such as human readable error messages or hardware specific error codes.
When non-standard fields are used there's a risk that the same name could be used by different implementations, causing unexpected behaviours. Implementors should reduce the risk of this by using a company name or code as a prefix for the field name. For example, a company called "Acme" might add fields for a hardware error code and a log message. Good names for these would be "AcmeHardwareError" and "AcmeLogMessage", reducing the risk of the same name being used by a different implementation.
Any extra field not defined by this specification and not recognised by the Service or the Client will be ignored.
Ignoring an unknown field will have no effect on the standard behaviour of the service or client. There will be no requirement to use undefined fields.
The service or client may use undefined fields for whatever purpose they require. Dependance on undefined fields will mean the client or service is non-standard and may impact interoperability.
Implementers should pick undefined field names to avoid name clashes.
1.2.3 - Command Sequence
Overview of the general sequencing of XFS4IoT command messages.
1.2.3.1 - Introduction
Once a service has been discovered and a connection created the client can send command messages to the service. Commands may cause the service to perform actions that are entirely software based, such as returning the current status, or they may cause actions to be performed by hardware, such as opening a shutter.
The sequence of messages passed between the service and the client is the same for all commands, independent of the command or interface being used.
Services may also send unsolic events directly to the client. This can happen at any time that the service connection is open. This could be during the processing of a command, or between commands.
Unsolic events may be sent at any time that there is a connection open between the service and the client.
1.2.3.2 - Message Types
The normal command message sequence will be:
`
All parts will be passed as standard messages as defined in the Messages section.
1.2.3.3 - Command Messages
The start of a command will be initiated by the client with a 'Command' message, requesting the service performs the specified action. The message use the standard header fields with:
- Type will be "command"
- Name will be the string defining the command to be executed as specified in the relevant interface specification.
- requestId will be a unique ID which is used to link future events to this invocation of the command.
The request ID given client and allows the client to link messages sent in response to the command back to the original command. For example, the completion event for this command will contain the same request id.
The value of the request IDs will be a unsigned integer, incremented between each command. The client is responsible for ensuring that each request ID is unique for a single connection. (Note that request ID's don't have to be unique across connections. The request is identified by a combination of the request ID and the connection.)
The request ID value 'zero' will be used for unsolic events, so the client should create request IDs starting with one or higher.
The request ID will be created by the client. It will be a unsigned integer strictly greater than zero, and will be incremented for each request.
The service will remember the last request ID and reject any request ID for a new command which is lower or equal to the previous request ID. Other than that the service will not track the request ID.
1.2.3.4 - Acknowledge Messages
As soon as the service has received and decoded the command message it will send an acknowledge message to indicate that it has the message. This will normally include the request ID so that the client can identify which command it relates to (unless there's some sort of error that stops the request ID being included).
Sending the acknowledge message immediately allows the client to handle network errors and lost messages more quickly. It can set a short timeout and expect to receive the acknowledge within that timeout, and continue with error handling if it doesn't.
Receiving the acknowledge doesn't give any guarantees about what the service will do with the command, or even that it can be executed. Any errors will be reported in the completion event for the command, not in the acknowledge.
The only exception is when it would be impossible for the service to send a useful completion event, such as if there's no request ID to include in the completion event. In this small number of cases an error code will be included in the acknowledge message.
Errors will include:
- invalidMessage : Message can't be decoded
- invalidRequestID : request ID is not an unsigned integer, or not greater than previous request IDs.
- tooManyRequests : There are currently too many requests queued by the service and the service can't queue any more.
Note: The error codes are intentionally defined to be very simple and not cover all cases. Extra information about exactly what caused a failure can be included in non-standard debugging fields in the acknowledge message.
1.2.3.5 - Event messages
During the processing of the command the service can send multiple solicited events, as defined in the interface documents. This is used to inform the client when something significant happens that it may need to react to, like a card being inserted or a key being pressed.
Each solicited event will contain the original request ID in the header, and will only be sent on the connection that the original command was received on, so that individual solicited events can be linked to the original command by the client.
For compatibility with future specification changes, and to permit custom extensions by service implementors, the client should ignore any events that it doesn't recognise.
The client will ignore any unknown events.
1.2.3.6 - Completion Messages
The normal processing of commands will complete with exactly one completion event. The exact type of the completion event will depend on the command and is defined in the interface specification for that command.
Exactly one completion event will be sent by the service for each executed command message.
If an acknowledge message with an error code is returned to the command message then the command will not be executed, and no completion even will be sent.
The completion event will contain the request ID from the original command message, so that the client can link the message back to the command. Once the completion event has been sent, that command handing has completed and no more messages will be sent for it.
After the completion event for a command message, with a particular request ID, has been sent then no more events will be sent with that request ID.
Each completion event will contain as much information as possible to avoid requiring extra events. For example, when a command is used to fetch information from the service then the information will be included in the completion event. When a command results in particular information, like reading a card, then that information is included in the completion event. The exact information included in each completion event is defined in the interface document that defines that completion event.
1.2.3.7 - Error Codes
Once a command is started, after the acknowledge message has been received, any error will be included in the completion event for that command. The interface specification will define which errors are valid for each completion event - no other errors will be returned by a service.
Common error codes are defined in the completionCode property of the completion message. Extra error properties may be defined in the interface definition for each command. Extra information about the details of the error may be included alongside the main error code, which may be used by the client in some cases, or may be used for diagnostics and logging.
1.2.3.8 - Unsolicited Event Messages
Service will also send 'unsolicited' events to the client to signal events that can happen at any time, independent of command handling. These can happen before, during, or after any command handling.
To allow clients to react to events quickly, unsolicited messages should be sent as soon as possible. As far as possible the service will send unsolicited events immediately. For example, it should avoid queueing events until after the current command has been processed if it doesn't have to.
Since unsolicited events aren't linked to command handling, they do not have a matching request ID. The event header will contain a request ID field (since all events do,) but the request ID will always be zero for unsolicited events. Unsolicited events are also broadcast to all clients, on all open connections.
unsolicited events will have a request ID of zero.
unsolicited events will be sent to all open connections.
The valid unsolicited events for each interface will be defined in the relevant documentation.
For compatibility with future specification changes, and to permit custom extensions by service implementors, the client should ignore any events that it doesn't recognise.
The client will ignore any unknown events.
1.2.3.9 - Command Queueing
Some commands can be executed in parallel. For example, a status command that returns the current status can always be executed immediately event if another long running command is being executed. Other commands may be blocked from parallel execution by mechanical or other restraints. For example, it's probably impossible to accept a card and capture a card at the same time on most card readers.
As far as possible services will attempt to execute commands in parallel. In particular, all commands that simply return information should be executed immediately even if other commands are in progress. It is up to the client to synchronise status information with ongoing actions.
When it's not possible to execute a command immediately, possibly because a mechanical operation is already using the hardware, then commands will be queued up and executed as soon as possible.
The acknowledge message is never queued.
`
When a command can not be executed immediately it will be queued until it can be executed.
Queued commands will be executed in the order they are received.
1.2.3.10 - Cancellation
A client can send a cancel command for an existing command at any time.
The cancel command will be a new command, with it's own request ID and it's own completion event.
The request ID of the command to cancel will be included as a parameter of the cancel command, allowing the service to identify the command to cancel.
The cancel command will complete straight away. It will not wait until the original command has been completed or cancelled. The cancel command will normally complete as "successful" even if the original command hasn't or can't be cancelled.
If the request ID of the original command is lower than any known request IDs then the cancel command will complete as "successful". This means that a cancel for a command that has already completed will always complete as "successful". The service won't make any other attempt to validate that the request ID was valid. The service will not track completed commands.
The cancel command will complete with an error if the request ID for the original command is invalid - that is, it's higher than any existing request ID.
The cancel command itself can not be cancelled. Any attempt to cancel a request ID for a cancel command will complete with an error.
Service will make a best attempt to cancel the command as soon as possible. However it may not always be possible to cancel a command immediately, or at all.
If a command can't be cancelled it will continue and complete as if no cancel message had been sent. All commands will end with exactly one completion message; either a normal completion message or a cancel completion message.
A cancelled completion message will be handled exactly like any other completion message. For example, there will be no more solicited events sent after the cancelled completion.
1.2.4 - End to End Security
Overview of the general end to end security support in XFS4IoT.
1.2.4.1 - Overview
A key priority for XFS4IoT is to improve security of the entire environment where XFS is used. This means securing not only the interface between the service and the hardware, or the interface between the client and the service, but providing security all the way from one end of an operation to the other.
For example, during a cash dispense operation the transaction will first be authorised by an authorising host which represents the owner of the cash in the device. That host will communicate through various other systems to the client application, the client application will communicate with the XFS4IoT service and the service will finally communicate with the hardware. Any part of that process is vulnerable to an attack which could lead to the wrong amount of cash being dispensed. XFS4IoT has been designed to block attacks at any point between the authorising host and the dispenser hardware - it is truly end to end.
Both data 'integrity' like this, and 'confidentiality' for things like card data, are important. XFS4IoT focuses on integrity since confidentiality is covered by TLS encryption of the network messages.
1.2.4.2 - General end to end sequence
End to end security involves communicating facts between two end points, and validating that those facts have not been changed or tampered with. Typically this would be between a Hardware Security Module (HSM) in a data-center, and a Hardware Security Element (HSE) built into a device such as a cash dispenser. The method of communication between these two ends does not matter since any tampering with the data will be detected.
The following diagram shows a typical system with the secure hardware end points in green. It shows two possible architectures, one with the client application running locally on the ATM, and the other with application running in the cloud.
`
The general sequence for an end to end security operation involves one system generating a token, and another system validating that the token has not been changed. This sequence looks roughly the same in both directions; for example an Authorising Host can create a 'Dispense Token' and the Dispenser will validate that token before dispensing cash. In the opposite direction, the dispenser can create a 'Present Status' token to protect information about the presented cash and the client can validate that the token is valid and has not been tampered with.
In both directions the sequence looks like this:
``
1.2.4.3 - Tokens
XFS4IoT implements end to end security using strong cryptography, such as HMAC values. Secret keys are shared between endpoints, ideally by using TR34 and TR31. The use of public key RKL ensures that only the correct endpoints have access to the end to end transactions.
The data relevant to the end to end transactions is separated out from the normal clear text properties passed in the JSON message formats, and is included in different "token" properties in the messages. Each token property is defined in the relevant interface documentation. For example, there is a "dispense token" for cash dispense actions and a "present status" token to protect the information about the last presented cash operation. These are defined in Dispenser service class documentation.
Tokens are encoded as a simple string which contains all of the information needed for that token, and also the information needed to keep it secure such as the HMAC value. Keeping all of the information together in this way ensures that a single HMAC can protect all of the data, and there is no possibility that part of the data could be changed.
Keeping the token as a simple string means that it is easy to handle for low-power hardware. For example, the token may need to be checked by embedded firmware, even if the service is running on a front end machine. To be fully end to end it must be checked on the hardware, so the format is kept simple.
The general format of a token is a string with a set of key=value pairs all comma separated and UTC8 encoded. The first pair will give the nonce. The last value will be an SHA256 HMAC, The UTC8 encoding is important so that the HMAC is consistent.
There will be multiple other key=value pairs, separated by commas. Keys can appear in any order. Key names are always upper case.
Tokens will not contain any extra whitespace.
To avoid possible parsing errors, binary data in tokens including the HMAC is encoded as simple hex values, rather than the normal BASE64 encoding. This is because BASE64 uses the "=" character which could be confused for the KEY/Value separator. Hex encoded data will be all upper case.
For similar reasons, the characters "=" and "," must never be used in any value data, including custom values. If custom key/value pairs are used then care must be taken that the value never contains those two characters.
The KEY=value pairs define what the token is used for. For example, the Dispenser service class has "DISPENSE1" and "PRESENTSTATUS" keys in different Tokens. The different key names ensures that tokens with different uses can not be reused by an attacker. "value" is the actually value of the data being protected and will be different for each operation.
NONCE is always the first key. HMAC256 is always the last key.
The set of standard key names and format for each value is defined in the relevant specification for each token type, including which keys are required and which are optional.
It is also permitted to include custom key values in a token. For example, a hardware dependent error code might be included. Unknown keys will be included in the HMAC calculation, but otherwise ignored. There must not be a dependency on custom keys. Care should be taken to avoid name clashes between keys, maybe by using a vendors name in the key name. For example, if the Acme Corporation wants to include "ERRORCODE" as a custom key name then they should call it something like "ACMEERRORCODE" and not "ERRORCODE".
The total token length will be limited to 1024 bytes to avoid the risk of buffer overflows. Any token longer than this will be treated as invalid data. The limit is in bytes not characters since UTC8 characters may include multiple bytes.
1.2.4.4 - Token Keys
End to End security tokens are made up of key/value pairs. There are various key names that are common to all types of tokens, plus key names which are only valid for specific token types. The following key names are valid for all tokens.
- NONCE : The token nonce value, which was initially exchanged between the end points and is used to ensure that every token is different and to avoid replay attacks. The nonce will always come at the start of the token (so that there is not too much constant leading data - this is important for security.)
The nonce value must be meet the cryptographic requirements for a nonce. It must be non-repeating - that is, the same nonce value must never be used twice. Code creating a nonce value should be carefully reviewed to make sure this is true.
There are two simply ways of guaranteeing this:
An incrementing integer can be used, as long as it always increments between every token. This must be true across restarts and power fails. The counter must not reset and repeat the same values. (Note that it doesn't actually matter that the value can be predicted.)
A strong random number can be used as long as the random number never repeats. This can be easy if there is a hardware random number generator available. If a pseudo-random number is used then the seed value needs to be carefully picked so that it never repeats (which would cause the random number to repeat.) Needing to track unique seed values might mean it's easier to simply use a persistent integer counter.
-
TOKENFORMAT : The version number of the token format. Currently this will always be "1"
-
TOKENLENGTH : The total number of bytes in the token, including the HMAC value, in decimal. This value will be exactly four digits and include leading zero's as required. Since this value has to include the length of itself, making it fixed length makes it easier to calculate. Note that this is bytes and not characters, since UTC8 characters may contain multiple bytes.
-
HMACSHA256 : The HEX encoded HMAC of all the preceding data up to and including the last equals after the HMACSHA256 key. The HMAC is always the last value - this makes it easy to calculate the HMAC since it can be calculated over all other data, converted to hex, then appended to the string. The HMAC will use SHA256 as the algorithm. The hex encoded data will be all upper case.
-
Other KEY=value pairs define what the token is used for. For example, the Dispenser service class has "DISPENSE1" and "PRESENTSTATUS" keys in different Tokens. The different key names ensures that tokens with different uses can not be reused by an attacker. "value" is the actually value of the data being protected and will be different for each operation.
1.2.4.5 - Token Examples
The general token format looks something like this:
NONCE=<nonce value>,TOKENFORMAT=1,TOKENLENGTH=<Length>,<KEY>=<value>,HMACSHA256=<HMAC>
For example, a dispense token might be:
NONCE=254611E63B2531576314E86527338D61,TOKENFORMAT=1,TOKENLENGTH=0164,DISPENSE1=50.00EUR,HMACSHA256=CB735612FD6141213C2827FB5A6A4F4846D7A7347B15434916FEA6AC16F3D2F2
The value used to calculate the HMAC is
NONCE=254611E63B2531576314E86527338D61,TOKENFORMAT=1,TOKENLENGTH=0164,DISPENSE1=50.00EUR,HMACSHA256=
A HMAC for this data, with SHA256 and a key of 112233445566778899AABBCCDDEEFF112233445566778899AABBCCDDEEFF, is
CB735612FD6141213C2827FB5A6A4F4846D7A7347B15434916FEA6AC16F3D2F2
This would be included in a dispense command message as:
{
"header": {
"type": "command",
"name": "dispenser.dispense",
"requestId": 456
},
"payload": {
...
"dispenseToken": "NONCE=254611E63B2531576314E86527338D61,TOKENFORMAT=1,TOKENLENGTH=0164,
DISPENSE1=50.00EUR,HMACSHA256=CB735612FD6141213C2827FB5A6A4F4846D7A7347B15434916FEA6AC16F3D2F2"
...
}
}
Similarly the PresentStatus might include a PresentStatus token:
NONCE=1414,TOKENFORMAT=1,TOKENLENGTH=0268,DISPENSEID=CB735612FD6141213C2827FB5A6A4F4846D7A7347B15434916FEA6AC16F3D2F2,
DISPENSED1=50.00EUR,PRESENTED1=YES,PRESENTEDAMOUNT1=50.00EUR,RETRACTED1=NO,
HMACSHA256=55D123E9EE64F0CC3D1CD4F953348B441E521BBACCD6998C6F51D645D71E6C83
which would be included in the present status completion event as:
{
"header": {
"requestId": 765,
"type": "completion",
"name": "dispenser.presentStatus"
},
"payload": {
...
"denomination": {
"currencies": [
{
"currencyID": "EUR",
"amount": 50
}
],
...
},
"presentState": "presented",
"token" : "NONCE=1414,TOKENFORMAT=1,TOKENLENGTH=0268,
DISPENSEID=CB735612FD6141213C2827FB5A6A4F4846D7A7347B15434916FEA6AC16F3D2F2,DISPENSED1=50.00EUR,PRESENTED1=YES,
PRESENTEDAMOUNT1=50.00EUR,RETRACTED1=NO,HMACSHA256=55D123E9EE64F0CC3D1CD4F953348B441E521BBACCD6998C6F51D645D71E6C83"
}
}
Note: token strings never have new lines or any white-space. New lines are included in examples only to make them more readable
In this example €50.00 was moved from the cassettes, possibly to a stacker, and €50.00 was then presented to the customer. The notes were not retracted so it should be assumed that the customer could have taken the notes.
1.2.4.6 - Encryption Key Management
To ensure strong security, secret symmetric encryption keys are shared between different endpoints.
The keys used for end to end encryption have fixed names. They are XFSAuthenticateHost and XFSAuthenticateDevice, where XFSAuthenticateHost is used by the host to create an HMAC, and XFSAuthenticateDevice is used by the hardware to create an HMAC. Both keys must be shared between both endpoints so that HMAC values can be both calculated and checked.
Ideally sharing the keys will be done using public key encryption, as defined in TR34. However, in some cases it may be necessary to pre-load keys into hardware in some other secure way, for example in legacy hardware that can not support TR34. The security of the whole system is only as good as the security of these keys so it is vital that this is done in as secure a way as possible.
The key details are defined by the TR31 specification which defines both key data and details such the intended use. This includes the algorithm that the key can be used with. Since TR31 defines the algorithm there is no need for algorithms to be negotiated in any other way - the two end points will effectively agree the algorithm to use by loading the relevant keys.
Encryption keys must be long enough to ensure security when used with a particular algorithm. For example, where SHA256 is used for the HMAC value the key must be at least 256 bits long to match the algorithm.
For simplicity, communication in each direction will be handled separately. So, for example, there will be a separate key for tokens passed in each direction. (Also there will be a separate nonce in each direction. See below.)
The details of the key management are covered by the shared key management interface. Any service that implements end to end security will implement this interface as part of its interface.
1.2.4.7 - Unique messages and replay attacks
To avoid 'replay attacks', where an attacker reuses an old message to replace a new one, it is important that all individual tokens are unique and the same data is not used multiple times. For example, it is common to have a dispense token for "10EUR" so that value (and its HMAC) will be the same for many transactions and could be reused by an attacker. To avoid this a "Nonce" value is included in each token. The nonce will be different for each transaction. This guarantees uniqueness.
There will be a different nonce for tokens passed in each direction. That is, there will be a command nonce and response nonce. Each nonce must be generated and checked at the same end of the communication, so the command nonce must be generated and checked by the device hardware. The response nonce must be generated and checked by the client. (Ideally in the host HSM.)
To fully avoid replay attacks the nonce must be agreed between the endpoints before it is used. An extra command on the interface is called by the client to fetch a new command nonce. This nonce is then remembered by both end points and included in each command token. Similarly, a response nonce must be generated by the client/host, passed to the service, and included in all response tokens. It should be possible to add the response nonce to existing messages, such as the PresentStatus command message for the cash dispenser.
1.2.4.8 - Example: A classic dispense operation
The following example shows how end to end security is used to protect a cash dispense operation during a classic ATM transaction.
Once a dispense has been performed it is important to accurately report the result. If an attacker can change the reported result then them might fake an error to make it look like cash was not presented to the customer, and tricking the banks into reversing the transaction - this is known as transaction reversal fraud.
To protect against this, the PresentStatus command returns a token that can not be tampered with. Note that this token goes in the opposite direction, from the hardware to the host. This means that the nonce now coming from the host rather than from the hardware. The nonce can be included in the PresentStatus command without needing to call an extra command.
1.2.4.9 - Example: Types of attacks that are blocked
Various types of attacks are blocked by end to end security. Some examples are given here.
A fake client attempts to issue a dispense command without authorisation. This is commonly known as a "black box" attack.
An attacker with control over communications tries to change details, for example to increase the amount of cash being dispensed. This is known as a "Man in the Middle" attack.
An attacker with control over communication stores a token and attempts to use it a second time. This is known as a "replay attack"
1.3 - Command Messages
2 - Common Interface
This chapter defines the Common interface functionality and messages.
2.2 - Command Messages
2.2.1 - Common.Status
This command is used to obtain the overall status of any XFS4IoT service. The status includes common status information and can include zero or more interface specific status objects, depending on the implemented interfaces of the service. It may also return vendor-specific status information.
Command Message
Completion Message
Event Messages
None2.2.2 - Common.Capabilities
This command retrieves the capabilities of the device. It may also return vendor specific capability information.
Command Message
Completion Message
Event Messages
None2.2.3 - Common.SetGuidanceLight
This command is used to set the status of the devices guidance lights. This includes defining the flash rate, the color and the direction. When a client tries to use a color or direction that is not supported then the Service Provider will return the generic completionCode unsupportedData.
Command Message
Completion Message
Event Messages
None2.2.4 - Common.PowerSaveControl
This command activates or deactivates the power-saving mode. If the Service Provider receives another execute command while in power saving mode, the Service Provider automatically exits the power saving mode, and executes the requested command. If the Service Provider receives an information command while in power saving mode, the Service Provider will not exit the power saving mode.
Command Message
Completion Message
Event Messages
2.2.5 - Common.SynchronizeCommand
This command is used to reduce response time of a command (e.g. for synchronization with display) as well as to synchronize actions of the different device classes. This command is intended to be used only on hardware which is capable of synchronizing functionality within a single device class or with other device classes.
The list of execute commands which this command supports for synchronization is retrieved in the synchronizableCommands value of Common.Capabilities.
This command is optional, i.e. any other command can be called without having to call it in advance. Any preparation that occurs by calling this command will not affect any other subsequent command. However, any subsequent execute command other than the one that was specified in the command input parameter will execute normally and may invalidate the pending synchronization. In this case the client should call Common.SynchronizeCommand again in order to start a synchronization.
Command Message
Completion Message
Event Messages
None2.2.6 - Common.SetTransactionState
This command allows the client to specify the transaction state, which the Service Provider can then utilize in order to optimize performance. After receiving this command, this Service Provider can perform the necessary processing to start or end the customer transaction. This command should be called for every Service Provider that could be used in a customer transaction. The transaction state applies to every session.
Command Message
Completion Message
Event Messages
None2.2.7 - Common.GetTransactionState
This command can be used to get the transaction state.
Command Message
Completion Message
Event Messages
None2.2.8 - Common.GetCommandNonce
Get a nonce to be included in an Authorisation Token for a command that will be used to ensure
end to end security.
The hardware will overwrite any existing stored Command nonce with this new value. The value will be stored for future authentication. Any Authorisation Token received will be compared with this stored nonce and if the Token doesn't contain the same nonce it will be considered invalid and rejected, causing the command that contains that Authentication Token to fail.
The nonce must match the algorithm used. For example, HMAC SHA256 means the nonce must be 256 bit/32 bytes.
Command Message
Completion Message
Event Messages
None3 - Card Reader Interface
This chapter defines the Card Reader interface functionality and messages.
3.1 - Summary
This interface allows for the operation of the following categories of card readers:
- Motorized card reader/writer
- Swipe card reader (writing facilities only partially included)
- Dip card reader
- Latched dip card reader
- Contactless chip card readers
- Permanent chip card readers (each chip is accessed through a unique service)
Some motorized card reader/writers have parking stations inside and can place identification cards there. Once a card is in its parking station another card can be accepted by the card reader. Cards may only be moved out of a parking station if there is no other card present in the media read/write position, the chip I/O position, the transport, or the entry/exit slot.
The following tracks/chips and the corresponding international standards are taken into account in this document:
- Track 1 - ISO 7811
- Track 2 - ISO 7811
- Track 3 - ISO 7811 / ISO 4909
- Cash Transfer Card Track 1 - (JIS I: 8 bits/char) Japan
- Cash Transfer Card Track 3 - (JIS I: 8 bits/char) Japan
- Front Track 1 - (JIS II) Japan
- Watermark - Sweden
- Chip (contacted) - ISO 7816
- Chip (contactless) - ISO 10536, ISO 14443 and ISO 18092
3.2 - General Information
3.3 - Command Messages
3.3.1 - CardReader.QueryIFMIdentifier
This command is used to retrieve the complete list of registration authority Interface Module (IFM) identifiers. The primary registration authority is EMVCo but other organizations are also supported for historical or local country requirements.
New registration authorities may be added in the future so applications should be able to handle the return of new (as yet undefined) IFM identifiers.
Command Message
Completion Message
Event Messages
None3.3.2 - CardReader.EMVClessQueryApplications
This command is used to retrieve the supported payment system applications available within an intelligent contactless card unit. The payment system application can either be identified by an AID or by the AID in combination with a Kernel Identifier. The Kernel Identifier has been introduced by the EMVCo specifications; see Reference [3].
Command Message
Completion Message
Event Messages
None3.3.3 - CardReader.EjectCard
This command is only applicable to motor driven card readers and latched dip card readers.
For motorized card readers the default operation is that the card is driven to the exit slot from where the user can remove it. The card remains in position for withdrawal until either it is taken or another command is issued that moves the card.
For latched dip readers, this command causes the card to be unlatched (if not already unlatched), enabling removal.
After successful completion of this command, a CardReader.MediaRemovedEvent is generated to inform the application when the card is taken.
Command Message
Completion Message
This event notifies the completion of the command and if successful includes the requested data.
Event Messages
3.3.4 - CardReader.RetainCard
The card is removed from its present position (card inserted into device, card entering, unknown position) and stored in the retain bin; applicable to motor-driven card readers only. The ID card unit sends a CardReader.RetainBinThresholdEvent if the storage capacity of the retain bin is reached. If the storage capacity has already been reached, and the command cannot be executed, an error is returned and the card remains in its present position.
Command Message
Completion Message
Event Messages
3.3.5 - CardReader.ResetCount
This function resets the present value for number of cards retained to zero. The function is possible for motor-driven card readers only.
The number of cards retained is controlled by the service and can be requested before resetting via Common.Status.
Command Message
Completion Message
Event Messages
3.3.6 - CardReader.SetKey
This command is used for setting the DES key that is necessary for operating a CIM86 module. The command must be executed before the first read command is issued to the card reader.
Command Message
Completion Message
This event notifies the completion of the command and if successful includes the requested data.
Event Messages
None3.3.7 - CardReader.ReadRawData
For motor driven card readers, the card unit checks whether a card has been inserted. If so, all specified tracks are read immediately. If reading the chip is requested, the chip will be contacted and reset and the ATR (Answer To Reset) data will be read. When this command completes the chip will be in contacted position. This command can also be used for an explicit cold reset of a previously contacted chip.
This command should only be used for user cards and should not be used for permanently connected chips.
If no card has been inserted, and for all other categories of card readers, the card unit waits for the period of time specified in the call for a card to be either inserted or pulled through. The next step is trying to read all tracks specified.
The CardReader.InsertCardEvent will be generated when there is no card in the card reader and the device is ready to accept a card. In addition to that, a security check via a security module (i.e. MM, CIM86) can be requested. If the security check fails however this should not stop valid data being returned. The response securityFail will be returned if the command specifies only security data to be read and the security check could not be executed, in all other cases ok will be returned with the data field of the output parameter set to the relevant value including hardwareError.
For non-motorized Card Readers which read track data on card exit, the invalidData error code is returned when a call to is made to read both track data and chip data.
If the card unit is a latched dip unit then the device will latch the card when the chip card will be read, i.e. chip is specified (see below). The card will remain latched until a call to CardReader.EjectCard is made.
For contactless chip card readers a collision of two or more card signals may happen. In this case, if the device is not able to pick the strongest signal, errorCardCollision will be returned.
Command Message
Completion Message
Event Messages
3.3.8 - CardReader.WriteRawData
For motor-driven card readers, the ID card unit checks whether a card has been inserted. If so, the data is written to the tracks.
If no card has been inserted, and for all other categories of devices, the ID card unit waits for the application specified timeout for a card to be either inserted or pulled through. The next step is writing the data to the respective tracks.
The CardReader.InsertCardEvent event will be generated when there is no card in the card reader and the device is ready to accept a card.
The application must pass the magnetic stripe data in ASCII without any sentinels. The data will be converted by the Service Provider (ref CardReader.ReadRawData). If the data passed in is too long the invalidError error code will be returned.
This procedure is followed by data verification.
If power fails during a write the outcome of the operation will be vendor specific, there is no guarantee that the write will have succeeded.
Command Message
Completion Message
This event notifies the completion of the command and if successful includes the requested data.
Event Messages
3.3.9 - CardReader.ChipIO
This command is used to communicate with the chip. Transparent data is sent from the application to the chip and the response of the chip is returned transparently to the application.
The identification information e.g. ATR of the chip must be obtained before issuing this command. The identification information for a user card or the Memory Card Identification (when available) must initially be obtained using CardReader.ReadRawData. The identification information for subsequent resets of a user card can be obtained using either CardReader.ReadRawData CardReader.ChipPower. The ATR for permanent connected chips is always obtained through CardReader.ChipPower.
For contactless chip card readers, applications need to specify which chip to contact with, as part of chipData, if more than one chip has been detected and multiple identification data has been returned by the CardReader.ReadRawData command.
For contactless chip card readers a collision of two or more card signals may happen. In this case, if the device is not able to pick the strongest signal, the cardCollision error code will be returned.
Command Message
Completion Message
Event Messages
3.3.10 - CardReader.Reset
This command is used by the application to perform a hardware reset which will attempt to return the card reader device to a known good state. This command does not over-ride a lock obtained by another application or service handle.
If the device is a user ID card unit, the device will attempt to either retain, eject or will perform no action on any user cards found in the device as specified in the input parameter. It may not always be possible to retain or eject the items as specified because of hardware problems. If a user card is found inside the device the CardReader.MediaInsertedEvent will inform the application where card was actually moved to. If no action is specified the user card will not be moved even if this means that the device cannot be recovered.
If the device is a permanent chip card unit, this command will power-off the chip.
For devices with parking station capability there will be one MediaInsertedEvent for each card found.
Command Message
Completion Message
This event notifies the completion of the command and if successful includes the requested data.
Event Messages
3.3.11 - CardReader.ChipPower
This command handles the power actions that can be done on the chip.
For user chips, this command is only used after the chip has been contacted for the first time using the CardReader.ReadRawData command. For contactless user chips, this command may be used to deactivate the contactless card communication.
For permanently connected chip cards, this command is the only way to control the chip power.
Command Message
Completion Message
Event Messages
3.3.12 - CardReader.ParkCard
This command is used to move a card that is present in the reader to a parking station. A parking station is defined as an area in the ID card unit, which can be used to temporarily store the card while the device performs operations on another card. This command is also used to move a card from the parking station to the read/write, chip I/O or transport position. When a card is moved from the parking station to the read/write, chip I/O or transport position (parkOut), the read/write, chip I/O or transport position must not be occupied with another card, otherwise the error cardPresent will be returned.
After moving a card to a parking station, another card can be inserted and read by calling, e.g., CardReader.ReadRawData or CardReader.ReadTrack.
Cards in parking stations will not be affected by any CardReader commands until they are removed from the parking station using this command, except for the CardReader.Reset command, which will move the cards in the parking stations as specified in its input as part of the reset action if possible.
Command Message
Completion Message
This event notifies the completion of the command and if successful includes the requested data.
Event Messages
None3.3.13 - CardReader.EMVClessConfigure
This command is used to configure an intelligent contactless card reader before performing a contactless transaction. This command sets terminal related data elements, the list of terminal acceptable applications with associated application specific data and any encryption key data required for offline data authentication.
This command should be used prior to CardReader.EMVClessPerformTransaction if the command. It may be called once on application start up or when any of the configuration parameters require to be changed. The configuration set by this command is persistent.
This command should be called with a complete list of acceptable payment system applications as any previous configurations will be replaced.
Command Message
Completion Message
Event Messages
None3.3.14 - CardReader.EMVClessPerformTransaction
This command is used to enable an intelligent contactless card reader. The transaction will start as soon as the card tap is detected.
Based on the configuration of the contactless chip card and the reader device, this command could return data formatted either as magnetic stripe information or as a set of BER-TLV encoded EMV tags.
This command supports magnetic stripe emulation cards and EMV-like contactless cards but cannot be used on storage contactless cards. The latter must be managed using the CardReader.ReadRawData and CardReader.ChipIO commands.
For specific payment system's card profiles an intelligent card reader could return a set of EMV tags along with magnetic stripe formatted data. In this case, two contactless card data structures will be returned, one containing the magnetic stripe like data and one containing BER-TLV encoded tags.
If no card has been tapped, the contactless chip card reader waits for the period of time specified in the command call for a card to be tapped.
For intelligent contactless card readers, any in-built audio/visual feedback such as Beep/LEDs, need to be controlled directly by the reader. These indications should be implemented based on the EMVCo and payment system's specifications.
Command Message
Completion Message
Event Messages
3.3.15 - CardReader.EMVClessIssuerUpdate
This command performs the post authorization processing on payment systems contactless cards.
Before an online authorized transaction is considered complete, further chip processing may be requested by the issuer. This is only required when the authorization response includes issuer update data; either issuer scripts or issuer authentication data.
The command enables the contactless card reader and waits for the customer to re-tap their card.
The contactless chip card reader waits for the period of time specified in the WFSExecute call for a card to be tapped.
Command Message
Completion Message
Event Messages
3.4 - Event Messages
3.4.1 - CardReader.MediaRetainedEvent
This specifies that the card was retained.
3.4.2 - CardReader.InsertCardEvent
This event notifies the application when the device is ready for the user to insert a card.
3.4.3 - CardReader.MediaInsertedEvent
This event notifies the application when the device is ready for the user to insert a card.
3.4.4 - CardReader.InvalidMediaEvent
This event specifies that the media the user is attempting to insert is not a valid card or it is a card but it is in the wrong orientation.
3.4.5 - CardReader.TrackDetectedEvent
This execute event notifies the application what track data the inserted card has, before the reading of the data has completed. This event will be posted once when tracks are detected during card insertion.
3.4.6 - CardReader.InvalidTrackDataEvent
This execute event specifies that a track contained invalid or no data.
3.4.7 - CardReader.MediaDetectedEvent
This is generated if media is detected during a CardReader.Reset. The parameter on the event informs the application of the position of the card on the completion of the reset. For devices with parking station capability there will be one event for each card found.
3.4.8 - CardReader.EMVClessReadStatusEvent
This notifies that the communication (i.e. the commands exchanged linked to the tap) between the card and the intelligent contactless card reader are complete. The application can use this event to display intermediate messages, progress of card read, audio signals or anything else that might be required. The intelligent contactless card reader will continue the processing and the result of the processing will be returned in the output of the CardReader.EMVClessPerformTransaction command.
3.5 - Unsolicited Messages
3.5.1 - CardReader.MediaRemovedEvent
This event specifies that the inserted card was manually removed by the user during the processing of a read command, during the processing of a CardReader.ChipIO, CardReader.ChipPower command, during or after a CardReader.RetainCard, CardReader.Reset operation, after an CardReader.EjectCard operation or after the card is removed by the user in a latched dip card unit.
3.5.2 - CardReader.CardActionEvent
This service event specifies that a card has been retained or ejected by either the automatic power on or power off action of the device.
3.5.3 - CardReader.RetainBinThresholdEvent
This specifies that the retain bin holding the retained cards has reached a threshold condition or the threshold condition is removed.
4 - Cash Management Interface
This chapter defines the Cash Management interface functionality and messages.
4.1 - Summary
This specification describes the functionality of an XFS4IoT compliant Cash Management interface. It defines the service-specific commands that can be issued to the service using the WebSocket endpoint.
This interface is to be used together with Dispenser and/or CashAcceptor interfaces to handle management of cash units, cash counts and banknote information.
4.2 - General Information
4.2.1 - Note Classification
Notes are classified by the XFS4IoT specification according to the following definitions:
-
Level 1 -- Note not recognized.
-
Level 2 -- Recognized counterfeit note.
-
Level 3 -- Suspected counterfeit note.
-
Level 4 -- Recognized note that is identified as genuine. This includes notes which are fit or unfit for recycling.
This definition allows support for legislative note handling standards that may exist in various countries and economic regions. Local requirements or device capability may dictate that notes are not classified as level 2 and level 3; the P6 string reported by Common.Capabilities CashAcceptor.counterfeitAction reports whether notes are classified into all 4 levels and whether level 2 or 3 notes can be returned to the customer.
The above classification levels can be used to support note handling functionality which includes:
-
The ability to remove counterfeit notes from circulation.
-
Reporting of recognized, counterfeit and suspected counterfeit notes.
-
Creating and reporting of note signatures in order to allow back-tracing of notes.
A note's classification can be changed based on the note's serial number, currency and value by specifying a classification list. A classification list can be used to re-classify a matching note to a lower level, including classifying a genuine note as unfit for dispensing. Once reclassified, the note will be automatically handled according to the local country specific note handling standard or legislation for the note's new note classification, including any level 2 or 3 note retention rules. Any reclassification will result in the normal events and behavior, for example a CashManagement.InfoAvailable event will reflect the note's reclassification. Reclassification can be used to make dynamic changes to note handling procedures without a software upgrade, enabling functionality such as taking older notes out of circulation or handling of counterfeit notes on a local basis.
Reclassification cannot be used to change a note's classification to a higher level, for example, a note recognized as counterfeit by the device cannot be reclassified as genuine. In addition, it is not possible to re-classify a level 2 note as level 1. No particular use case has been identified for reclassifying Level 3 and 4 notes as level 1, but there is no reason to restrict this reclassification.
Classification lists can be specified using CashManagement.SetClassificationList and retrieved using CashManagement.GetClassificationList. A classification list is a superset of the XFS 3.x blacklist; any items specified as level 2 in the classification list are considered part of the blacklist. However support for the old blacklist commands has been removed as it may lead to overlap and confusion.
The classification list functionality can use a mask to specify serial numbers. The mask is defined as follows: A '?' character (0x003F) is the wildcard used to match a single Unicode character, and a '*' character (0x002A) is the wildcard used to match one or more Unicode characters.
For example, "S8H9??16?4" would represent a match for the serial numbers "S8H9231654" and "S8H9761684". A mask of "HD90*2" would be used in order to match serial numbers that begin with "HD90" and end with "2", for example "HD9028882", "HD9083276112". Note that the mask can only use one asterisk, and if a real character is required then it must be preceded by a backslash, for example: '\\' for a backslash, '\*' for an asterisk or '\?' for a question mark. Note that this flexibility means that it is possible to overlap definitions, for example "HD90*" and "HD902*" would both match on the serial number HD9028882".
4.3 - Command Messages
4.3.1 - CashManagement.GetCashUnitInfo
This command is used to obtain information regarding the status and contents of cash units.
It is possible that multiple cash units may be associated with one physical cash unit. This should only occur if the physical cash unit is capable of handling this situation, i.e. if it can store multiple denominations and report meaningful count and replenishment information for each denomination or if it can store retracted and rejected items as separate units and report meaningful count and replenishment information for each of them.
Starting with XFS 4.0 the concept of logical cash units is removed from XFS services. Only physical units are reported. The former logical cash counts can be easily calculated from the given cash counts.
Command Message
Completion Message
Event Messages
None4.3.2 - CashManagement.GetTellerInfo
This command only applies to Teller devices. It allows the client to obtain counts for each currency assigned to the teller. These counts represent the total amount of currency dispensed by the teller in all transactions.
This command also enables the client to obtain the position assigned to each teller. If the input parameter is NULL, this command will return information for all tellers and all currencies. The teller information is persistent.
Command Message
Completion Message
Event Messages
None4.3.3 - CashManagement.GetItemInfo
This command is used to get information about detected items. It can be used to get information about individual items, all items of a certain level, or all items that have information available. This information is available from the point where the first CashManagement.InfoAvailableEvent event is generated until one of the following commands is executed:
CashAcceptor.CashInStart, CashAcceptor.CashIn, CashAcceptor.CashInRollback, CashAcceptor.CashInEnd, CashAcceptor.Retract, CashAcceptor.Reset, CashAcceptor.CreateP6Signature, CashAcceptor.Replenish, CashAcceptor.CashUnitCount. Dispenser.Dispense, Dispenser.Count, Dispenser.Present, Dispenser.Retract, Dispenser.Reject, Dispenser.OpenShutter, Dispenser.CloseShutter, Dispenser.Reset, CashManagement.StartExchange, CashManagement.EndExchange, CashManagement.CalibrateCashUnit, Dispenser.TestCashUnits.
Command Message
Completion Message
Event Messages
None4.3.4 - CashManagement.GetClassificationList
This command is used to retrieve the entire note classification information pre-set inside the device or set via the CashManagement.SetClassificationList command. This provides the functionality to blacklist notes and allows additional flexibility, for example to specify that notes can be taken out of circulation by specifying them as unfit. Any items not returned in this list will be handled according to normal classification rules.
Command Message
Completion Message
Event Messages
None4.3.5 - CashManagement.SetTellerInfo
This command allows the client to initialize counts for each currency assigned to the teller. The values set by this command are persistent. This command only applies to Teller ATMs.
Command Message
Completion Message
Event Messages
4.3.6 - CashManagement.SetCashUnitInfo
This command is used to adjust information about the status and contents of the cash units present in the device. Only fields that are to be changed need to be set in the payload of this command. Values that are not meant to change, can be ommitted.
This command generates the CashManagement.CashUnitInfoChangedEvent to inform clients that cash unit information has been changed.
This command can be used to change software counters, thresholds and the client lock. Other fields in the input structure will only take effect, if used in exchange state.
The following fields of the structure may be updated by this command outside of the exchange state:
count
logicalCount
cashInCount
maximum
appLock
noteNumberList (contents must be consistent with ulCount)
initialCount
dispensedCount
presentedCount
retractedCount
rejectCount
minimum
Any other changes must be performed while in an exchange state.
The values set by this command are persistent.
Command Message
Completion Message
Event Messages
4.3.7 - CashManagement.OpenSafeDoor
This command unlocks the safe door or starts the time delay count down prior to unlocking the safe door, if the device supports it. The command completes when the door is unlocked or the timer has started.
Command Message
Completion Message
Event Messages
None4.3.8 - CashManagement.StartExchange
This command puts the device in an exchange state, i.e. a state in which cash units can be emptied, replenished, removed or replaced. Other than the updates which can be made via the CashManagement.SetCashUnitInfo command, outside of an exchange state, all changes to a cash unit must take place while the cash unit is in an exchange state.
The command returns current cash unit information in the form described in the documentation of the CashManagement.CashUnitInfo command. This command will also initiate any physical processes which may be necessary to make the cash units accessible. Before using this command a client should first have obtained exclusive control of the CashManagement interface.
This command may return a successful completion even if CashManagement.CashUnitErrorEvents are generated. If this command returns a successful completion the device is in an exchange state.
In Exchange state the CashManagement.SetCashUnitInfo command can be used multiple times to adjust the cash unit information, until the CashManagement.EndExchange command is performed.
While in an exchange state the device will process all requests, excluding cash related commands other than CashManagement.EndExchange, Dispenser.SetMixTable and Reset commands (e.g. Dispenser.Reset).
Any other command will result in the error "exchangeActive" being generated.
If an error is returned by this command, the response will include current cash unit information.
Command Message
Completion Message
Event Messages
4.3.9 - CashManagement.EndExchange
This command will end the exchange state. If any physical action took place as a result of the CashManagement.StartExchange command then this command will cause the cash units to be returned to their normal physical state, including depositing any remaining items where exchangeType is "depositInto". Any necessary device testing will also be initiated.
CashManagement.SetCashUnitInfo does not need to be called if the Service can obtain cash unit information from self-configuring cash units.
If an error occurs during the execution of this command, then the client must issue a CashManagement.CashUnitInfo to determine the cash unit information.
A CashManagement.CashUnitErrorEvent will be sent for any cash unit which cannot be successfully updated. If no cash units could be updated then a error code will be returned and CashManagement.CashUnitErrorEvent events generated for every cash unit that could not be updated.
Even if this command does not return a successful completion the exchange state has ended.
Command Message
Completion Message
Event Messages
4.3.10 - CashManagement.CalibrateCashUnit
This command will cause a vendor dependent sequence of hardware events which will calibrate one cash unit. This is necessary if a new type of bank note is put into the cash unit as the command enables the ATM to obtain the measures of the new bank notes.
This command cannot be used to calibrate cash units which have been locked by the client. A error code will be returned and a CashManagement.CashUnitErrorEvent generated.
Command Message
Completion Message
Event Messages
4.3.11 - CashManagement.SetClassificationList
This command is used to specify the entire note classification list. Any items not specified in this list will be handled according to normal classification rules. This information is persistent. Information set by this command overrides any existing classification list. If a note is reclassified, it is handled as though it was a note of the new classification. For example, a fit note reclassified as unfit would be treated as though it were unfit, which may mean that the note is not dispensed. Reclassification cannot be used to change a note’s classification to a higher level, for example, a note recognized as counterfeit by the device cannot be reclassified as genuine. In addition, it is not possible to re-classify a level 2 note as level 1. If two or more classification elements specify overlapping note definitions, but different level values then the first one takes priority.
Command Message
Completion Message
Event Messages
None4.4 - Event Messages
4.4.1 - CashManagement.CashUnitErrorEvent
This event is generated if there is a problem with a cash unit during the execution of a command.
4.4.2 - CashManagement.NoteErrorEvent
This event specifies the reason for a note detection error during the execution of a command.
4.4.3 - CashManagement.InfoAvailableEvent
This execute event is generated when information is available for items detected during the cash processing operation.
4.4.4 - CashAcceptor.ShutterStatusChangedEvent
Within the limitations of the hardware sensors this service event is generated whenever the status of a shutter changes. The shutter status can change because of an explicit, implicit or manual operation depending on how the shutter is operated.
4.4.5 - Dispenser.ItemsTakenEvent
This event is generated when items presented to the user have been taken. This event may be generated at any time.
4.5 - Unsolicited Messages
4.5.1 - CashManagement.SafeDoorOpenEvent
This event specifies that the safe door has been opened.
4.5.2 - CashManagement.SafeDoorClosedEvent
This event specifies that the safe door has been closed.
4.5.3 - CashManagement.CashUnitInfoChangedEvent
This service event is generated under the following circumstances:
-
It is generated whenever status changes. For instance, a cash unit has been removed or inserted, or a cash unit has become empty or full.
-
This event will also be generated for every cash unit changed in any way (including changes to counts, e.g. count, rejectCount, initialCount, dispensedCount and presentedCount) as a result of the CashManagement.SetCashUnitInfo command.
-
This event will also be fired when any change is made to a cash unit by the following commands, except for changes to counts (e.g. count, rejectCount, initialCount, dispensedCount and presentedCount):
- In addition this event will be generated when a cash unit has been counted during the CashAcceptor.CashUnitCount command execution.
When a cash unit is removed, the status of the cash
unit becomes missing.
If a new cash unit is inserted the cash unit structure reported by the last CashManagement.GetCashUnitInfo command is no longer valid. In that case a client should issue a CashManagement.GetCashUnitInfo command after receiving this event to obtain updated cash unit information.
4.5.4 - CashManagement.TellerInfoChangedEvent
This service event is generated when the counts assigned to a teller have changed. This event is only returned as a result of a CashManagement.SetTellerInfo command.
4.5.5 - CashManagement.CashUnitThresholdEvent
This user event is generated when a threshold condition has occurred in one of the cash units.
This event can be triggered either by hardware sensors in the device or by the count reaching the minimum or maximum value as specified in the GetCashUnitInfo structure.
The client can check if the device has hardware sensors by querying the hardwareSensor field of the cash unit structure. If a cash unit has this capability then threshold events based on hardware sensors will be triggered if the maximum or minimum values are not used or are set to zero.
5 - Dispenser Interface
This chapter defines the Dispenser interface functionality and messages.
5.1 - Summary
This specification describes the functionality of an XFS4IoT compliant Cash Dispenser interface. It defines the service-specific commands that can be issued to the service using the WebSocket endpoint.
Persistent values are maintained through power failures, open sessions, close session and system resets.
This specification covers the dispensing of items. An "item" is defined as any media that can be dispensed and includes coupons, documents, bills and coins.
5.2 - Command Messages
5.2.1 - Dispenser.GetMixTypes
This command is used to obtain a list of supported mix algorithms and available house mix tables.
Command Message
Completion Message
Event Messages
None5.2.2 - Dispenser.GetMixTable
This command is used to obtain the house mix table specified by the supplied mix number.
Command Message
Completion Message
Event Messages
None5.2.3 - Dispenser.GetPresentStatus
This command is used to obtain the status of the most recent attempt to dispense and/or present items to the customer from a specified output position. The items may have been dispensed and/or presented as a result of the Dispenser.Present or Dispenser.Dispense command. This status is not updated as a result of any other command that can dispense/present items.
This value is persistent and is valid until the next time an attempt is made to present or dispense items to the customer.
The denominations reported by this command may not accurately reflect the operation if the cash units have been re-configured (e.g. if the values associated with a cash unit are changed, or new cash units are configured).
Command Message
Completion Message
Event Messages
None5.2.4 - Dispenser.Denominate
This command provides a denomination. A denomination specifies the number of items which are required from each cash unit in order to satisfy a given amount. The denomination depends upon the currencies, the mix algorithm and any partial denomination supplied by the client.
This command can also be used to validate that any denomination supplied by the client can be dispensed.
If items of differing currencies are to be included in the same denomination then the currencies array has one entry per currency. Alternativly the currency information can be omitted and the mix number must be 0 ("individual").
If the cashBox field returned by the Dispenser.Capabilites command is TRUE then, if the entire denomination cannot be satisfied, a partial denomination will be returned with the remaining amount to be supplied from the teller's cash box.
This command can be used in four different ways:
1. In order to check that it is possible to dispense a given denomination. The input parameters to the command are currency and denomination, with a mix number of 0 ("individual") and an amount of zero. If items of differing currencies are to be dispensed then the currencies array needs one item per currency.
2. In order to validate that a given amount matches a given denomination and that it is possible to dispense the denomination. The input parameters to the command should be amount, currency and denomination, with a mix number of 0 ("individual").
3. In order to obtain a denomination of a given amount. The input parameters supplied should be amount, currency and mix number.
4. In order to complete a partial denomination of a given amount. In this case the input parameters to the command should be currency, amount, mix number and either a partially specified denomination or a minimum amount from the cash box. A completed denomination is returned. cashBox of the denomination structure may be updated as a result of this command.
Command Message
Completion Message
Event Messages
5.2.5 - Dispenser.Dispense
This command performs the dispensing of items to the customer. The command provides the same functionality as the Dispenser.Denominate command plus the additional functionality of dispensing the items. If items of differing currencies are to be dispensed then the currencies array has one entry per currency. Alternativly the currency information can be omitted and the mix number must be 0 ("individual"). However, these restrictions do not apply if a single currency is dispensed with non-currency items, such as coupons.
The Dispenser.Dispense command can be used in the following ways:
1. The input parameters to the command are amounts, currencies and denomination. The mix number is 0 ("individual"). In this case, the denomination is checked for validity and, if valid, is dispensed.
2. The input parameters are amounts, currencies and mix number. In this case the amount is denominated and, if this succeeds, the items are dispensed.
3. If the amount and currency information is omitted and a denomination is supplied with a mix number of 0 ("individual") the denomination is checked for validity and, if valid, is dispensed.
4. The command will calculate a partial denomination of a given amount and dispense the complete denomination. In this case the input parameters to the command should be currencies, amounts, mix number and either a partially specified denomination or a minimum amount from the cash box. The cash box amount may be updated as a result of this command.
If the cashBox field returned by the Dispenser.Capabilities command is TRUE then, if the entire denomination cannot be satisfied, a partial denomination will be returned with the remaining amount to be supplied from the teller's cash box.
If the device is a Teller Dispenser, the input field position can be set to "default". If this is the case the tellerID is used to perform the dispense operation to the assigned teller position.
It will be necessary to use the Dispenser.Present command to present the items to the user. If the Dispenser does not have an intermediate stacker the Dispenser.Present command does not need to be called and does not serve any purpose.
Note that a level 4 note can be dispensed, but is not necessarily presented to the customer. e.g. a note can be skewed, or can be unfit for dispensing.
The values in the completion messsage report the amount dispensed and the number of items dispensed from each cash unit.
Command Message
Completion Message
Event Messages
- CashManagement.CashUnitThresholdEvent
- Dispenser.DelayedDispenseEvent
- Dispenser.StartDispenseEvent
- CashManagement.CashUnitErrorEvent
- Dispenser.ItemsTakenEvent
- Dispenser.PartialDispenseEvent
- Dispenser.SubDispenseOkEvent
- Dispenser.IncompleteDispenseEvent
- CashManagement.NoteErrorEvent
- CashManagement.InfoAvailableEvent
- Dispenser.ShutterStatusChangedEvent
5.2.6 - Dispenser.Present
This command will move items to the exit position for removal by the user. If a shutter exists, then it will be implicitly controlled during the present operation, even if the shutterControl capability is set to FALSE. The shutter will be closed when the user removes the items or the items are retracted. If position is "default" the position set in the Dispenser.Dispense command which caused these items to be dispensed will be used.
When this command successfully completes the items are in customer access.
If Dispenser.Present was called as part of a sub-dispense operation, the completion message includes details about remaining bunches. The field additionalBunches specifies, if there are any additional bunches to be dispensed to the customer and the field bunchesRemaining specifies the number of outstanding subdispense operations.
Command Message
Completion Message
Event Messages
5.2.7 - Dispenser.Reject
This command will move items from the intermediate stacker and transport them to a reject cash unit (i.e. a cash unit with type "rejectCassette"). The count field of the reject cash unit is incremented by the number of items that were thought to be present at the time of the reject or the number counted by the device during the reject. Note that the reject bin count is unreliable.
Command Message
Completion Message
Event Messages
5.2.8 - Dispenser.Retract
This command will retract items which may have been in customer access from an output position or from internal areas within the Dispenser. Retracted items will be moved to either a retract cash unit, a reject cash unit, item cash units, the transport or the intermediate stacker. After the items are retracted the shutter is closed automatically, even if the shutterControl capability is set to FALSE.
If items are moved to a retract cash unit (i.e. a cash unit with type "retractCassette"), then the count field of the retract cash unit must be incremented by 1 to specify the number of retracts. If items are moved to any other cash unit (e.g. a cash unit with type "rejectCassette") then the count field of the cash unit must be incremented by the number of items that were thought to be present at the time the Dispenser.Retract command was issued or the number counted by the device during the retract. Note that reject bin counts are unreliable.
Command Message
Completion Message
Event Messages
5.2.9 - Dispenser.OpenShutter
This command opens the shutter.
Command Message
Completion Message
Event Messages
5.2.10 - Dispenser.CloseShutter
This command closes the shutter.
Command Message
Completion Message
Event Messages
5.2.11 - Dispenser.SetMixTable
This command is used to set up the mix table specified by the mix number. Mix tables are persistent and are available to all clients in the system. An amount can be specified as different denominations within the mix table. If the amount is specified more than once the Service Provider will attempt to denominate or dispense the first amount in the table. If this does not succeed (e.g. because of a cash unit failure) the Service Provider will attempt to denominate or dispense the next amount in the table. The Service Provider can only dispense amounts which are explicitly mentioned in the mix table.
If a mix number passed in already exists then the information is overwritten with the new information.
Command Message
Completion Message
Event Messages
None5.2.12 - Dispenser.Reset
This command is used by the client to perform a hardware reset which will attempt to return the Dispenser device to a known good state. This command does not over-ride a lock obtained through Common.Lock (TODO) on another client or service handle.
The device will attempt to move any items found anywhere within the device to the position specified within the command payload. This may not always be possible because of hardware problems.
If items are found inside the device the Dispenser.MediaDetectedEvent will be generated and will inform the client where the items were actually moved to.
If an exchange state is active then this command will end the exchange state (even if this command does not complete successfully).
On a recycling device this command is not accepted if a cash-in transaction is active and will return a "deviceNotReady" error.
If items are moved to a retract cash unit (i.e. a cash unit with type "retractCassette"), then the count field of the retract cash unit must be incremented by 1 to specify the number of operations that changed the count. If items are moved to any other cash unit (e.g. a cash unit with type "rejectCassette), then the count field of the cash unit must be incremented either by the number of items that were present at the time the Dispenser.Reset command was issued or the number counted by the device during the Dispenser.Reset command. Note that reject bin counts are unreliable.
Command Message
Completion Message
Event Messages
5.2.13 - Dispenser.TestCashUnits
This command is used to test cash units following replenishment. The command payload specifies where items dispensed as a result of this command should be moved to. All cash units which are testable (i.e. that have a status of "ok" or "low" and no client lock in the cash unit) are tested. If the hardware is able to do so tests are continued even if an error occurs while testing one of the cash units. The command completes with success completion message if the Service successfully manages to test all of the testable cash units regardless of the outcome of the test. This is the case if all testable cash units could be tested and a dispense was possible from at least one of the cash units.
A CashManagement.CashUnitErrorEvent will be sent for any cash unit which cannot be tested or which failed the test. If all the cash units could not be tested or no cash units are testable then a "cashUnitError" code will be returned and CashManagement.CashUnitErrorEvents generated for every cash unit that encountered a problem. The operation performed to test the cash units is vendor dependent. Items may be dispensed or transported into a reject bin as a result of this command.
If no cash units are testable then a "cashUnitError" code will be returned and CashManagement.CashUnitErrorEvents will be generated for every cash unit.
Command Message
Completion Message
Event Messages
5.2.14 - Dispenser.Count
This command empties the specified cash unit(s). All items dispensed from the cash unit are counted and moved to the specified output location.
The number of items counted can be different from the number of items dispensed in cases where the Dispenser has the ability to detect this information. If the Dispenser cannot differentiate between what is dispensed and what is counted then dispensed will be the same as counted.
Upon successful Dispenser.Count command execution the cash unit(s) count field is reset.
Command Message
Completion Message
Event Messages
5.2.15 - Dispenser.PrepareDispense
On some hardware it can take a significant amount of time for the dispenser to get ready to dispense media. On this type of hardware the Dispenser.PrepareDispense command can be used to improve transaction performance.
If this command is supported (see the prepareDispense capability) then clients can help to improve the time taken to dispense media by issuing this command as soon as the client knows that a dispense is likely to happen. This command either prepares the device for the next dispense operation, or terminates the dispense preparation if the subsequent dispense operation is no longer required.
With the exception of the Dipenser.Denominate and Dispenser.Dispense commands, which will not stop the dispense preparation, any execute command on Dispenser or CashAcceptor will automatically stop the dispense preparation.
If this command is executed and the device is already in the specified action state, then this execution will have no effect and will complete with a successful completion message.
Command Message
Completion Message
Event Messages
None5.3 - Event Messages
5.3.1 - CashManagement.CashUnitErrorEvent
This event is generated if there is a problem with a cash unit during the execution of a command.
5.3.2 - CashManagement.CashUnitThresholdEvent
This user event is generated when a threshold condition has occurred in one of the cash units.
This event can be triggered either by hardware sensors in the device or by the count reaching the minimum or maximum value as specified in the GetCashUnitInfo structure.
The client can check if the device has hardware sensors by querying the hardwareSensor field of the cash unit structure. If a cash unit has this capability then threshold events based on hardware sensors will be triggered if the maximum or minimum values are not used or are set to zero.
5.3.3 - Dispenser.DelayedDispenseEvent
This event is generated if the start of a dispense operation has been delayed.
5.3.4 - Dispenser.StartDispenseEvent
This event is generated when a delayed dispense operation begins.
5.3.5 - Dispenser.PartialDispenseEvent
This event is generated when a dispense operation is divided into several sub-dispense operations because the hardware capacity of the Dispenser is exceeded.
5.3.6 - Dispenser.SubDispenseOkEvent
This event is generated when one of the sub-dispense operations into which the dispense operation was divided has finished successfully. To present the items to the customer a Dispenser.Present command has to be issued. Note that in this case the values in the payload structure report the amount and number of each denomination dispensed in the sub-dispense operation.
5.3.7 - Dispenser.IncompleteDispenseEvent
This event is generated during Dispenser.Dispense when it has not been possible to dispense the entire denomination but part of the requested denomination is on the intermediate stacker or in customer access. Note that in this case the values in this structure report the amount and number of each denomination that are in customer access or on the intermediate stacker. Dispenser.GetPresentStatus can be used to determine whether the items are in customer access.
5.3.8 - CashManagement.NoteErrorEvent
This event specifies the reason for a note detection error during the execution of a command.
5.3.9 - CashManagement.InfoAvailableEvent
This execute event is generated when information is available for items detected during the cash processing operation.
5.3.10 - Dispenser.IncompleteRetractEvent
This event is sent when a retract or reset command has completed with an error and not all of the items have been retracted.
5.3.11 - CashManagement.CashUnitInfoChangedEvent
This service event is generated under the following circumstances:
-
It is generated whenever status changes. For instance, a cash unit has been removed or inserted, or a cash unit has become empty or full.
-
This event will also be generated for every cash unit changed in any way (including changes to counts, e.g. count, rejectCount, initialCount, dispensedCount and presentedCount) as a result of the CashManagement.SetCashUnitInfo command.
-
This event will also be fired when any change is made to a cash unit by the following commands, except for changes to counts (e.g. count, rejectCount, initialCount, dispensedCount and presentedCount):
- In addition this event will be generated when a cash unit has been counted during the CashAcceptor.CashUnitCount command execution.
When a cash unit is removed, the status of the cash
unit becomes missing.
If a new cash unit is inserted the cash unit structure reported by the last CashManagement.GetCashUnitInfo command is no longer valid. In that case a client should issue a CashManagement.GetCashUnitInfo command after receiving this event to obtain updated cash unit information.
5.4 - Unsolicited Messages
5.4.1 - Dispenser.ItemsTakenEvent
This event is generated when items presented to the user have been taken. This event may be generated at any time.
5.4.2 - Dispenser.ItemsPresentedEvent
This event specifies that items have been presented to the user during a count operation and need to be taken.
5.4.3 - Dispenser.MediaDetectedEvent
This service event is generated if media is detected during a reset command. The payload on the event informs the client of the position of the media after the reset completes. If the device has been unable to successfully move the items found then this payload will be ommitted.
5.4.4 - Dispenser.ShutterStatusChangedEvent
Within the limitations of the hardware sensors this event is generated whenever the status of a shutter changes. The shutter status can change because of an explicit, implicit or manual operation depending on how the shutter is operated.
6 - Cash Acceptor Interface
This chapter defines the Cash Acceptor interface functionality and messages.
6.1 - Summary
This specification describes the functionality of an XFS4IoT compliant Cash Acceptor interface. It defines the service-specific commands that can be issued to the service using the WebSocket endpoint.
Persistent values are maintained through power failures, open sessions, close session and system resets.
This specification covers the acceptance of items. An "item" is defined as any media that can be accepted and includes coupons, documents, bills and coins. However, if coins and bills are both to be accepted separate Services must be implemented for each.
6.2 - Command Messages
6.2.1 - CashAcceptor.GetBanknoteTypes
This command is used to obtain information about the banknote types that can be detected by the banknote reader.
Command Message
Completion Message
Event Messages
None6.2.2 - CashAcceptor.GetCashInStatus
This command is used to get information about the status of the currently active cash-in transaction or in the case where no cash-in transaction is active the status of the most recently ended cash-in transaction. This value is persistent and is valid until the next command CashAcceptor.CashInStart.
Command Message
Completion Message
Event Messages
None6.2.3 - CashAcceptor.GetPositionCapabilities
This command allows the client to get additional information about the use assigned to each position available in the device.
Command Message
Completion Message
Event Messages
None6.2.4 - CashAcceptor.GetReplenishTarget
This command is used to determine which cash units can be specified as target cash units for a given source cash unit with the CashAcceptor.Replenish command. For example it can be used to determine which targets can be used for replenishment from a replenishment container or from a recycle cash unit.
Command Message
Completion Message
Event Messages
None6.2.5 - CashAcceptor.GetDevicelockStatus
This command is used to retrieve the lock/unlock statuses of the CashAcceptor device and each of its cash units. If the physical lock/unlock of both the CashAcceptor device and the cash units are not supported then an error will be returned.
Command Message
Completion Message
Event Messages
None6.2.6 - CashAcceptor.GetCashUnitCapabilities
This command is used to retrieve information on cash unit capabilities. It does not provide information on status or counters of cash units. This command can be seen as an extension to the CashManagement.CashUnitInfo command as it will always result in the same contents with regard to number and the cash unit information.
Command Message
Completion Message
Event Messages
None6.2.7 - CashAcceptor.GetDepleteSource
This command is used to determine which cash units can be specified as source cash units for a given target cash unit with the CashAcceptor.Deplete command. For example it can be used to determine which sources can be used for depletion to a replenishment container or to a cash-in cash unit.
Command Message
Completion Message
Event Messages
None6.2.8 - CashAcceptor.GetCashUnitCountStatus
During normal processing it is possible that the count of a cash unit can become inaccurate due to a jam, mis-pick or other error situation. In this case the GetCashUnitCountStatus command could be used to report which cash units are known to have an inaccurate count. The client can then issue a CashAcceptor.CashUnitCount command for only those cash units if supported. Or alternatively the notes could be manually counted as part of a replenishment operation. This command returns the cash unit count status of all cash units.
Command Message
Completion Message
Event Messages
None6.2.9 - CashAcceptor.GetPresentStatus
This command is used to obtain the status of the most recent attempt to present or return items to the customer. This information includes the number of items previously moved to the output position and the number of items which have yet to be returned as a result of the following commands: CashIn, CashInRollback, PreparePresent, PresentMedia, OpenShutter (In the case of returning multiple bunches)
Command Message
Completion Message
Event Messages
None6.2.10 - CashAcceptor.CashInStart
Before initiating a cash-in operation, a client must issue the CashAcceptor.CashInStart command to begin a cash-in transaction. During a cash-in transaction any number of CashAcceptor.CashIn commands may be issued. The transaction is ended when either a CashAcceptor.CashInRollback, CashAcceptor.CashInEnd, CashAcceptor.Retract or CashAcceptor.Reset command is sent. Where Capability shutterControl == FALSE this command precedes any explicit operation of the shutters.
CashAcceptor.Retract will terminate a transaction. In this case CashAcceptor.CashInEnd, CashAcceptor.CashInRollback and CashAcceptor.CashIn will report noCashInActive. If an client wishes to determine where the notes went during a transaction it can execute a CashUnitInfo before and after the transaction and then derive the difference.
A hardware failure during the cash-in transaction does not reset the note number list information; instead the note number list information will include items that could be accepted and identified up to the point of the hardware failure.
Exchange: This command can be used during an Exchange (exchangeType == depositInto) to deposit items accepted from the input position.
Command Message
Completion Message
Event Messages
None6.2.11 - CashAcceptor.CashIn
This command moves items into the cash device from an input position.
On devices with implicit shutter control, the CashAcceptor.InsertItems event will be generated when the device is ready to start accepting media.
The items may pass through the banknote reader for identification. Failure to identify items does not mean that the command has failed - even if some or all of the items are rejected by the banknote reader, the command may return success. In this case one or more CashAcceptor.InputRefuse events will be sent to report the rejection. See also paragraph below regarding returning refused items.
If the device does not have a banknote reader then the completion message will be empty.
If the device has a cash-in stacker then this command will cause inserted level 4 items to be moved there after validation. Level 2 and level 3 items may also be moved to the cash-in stacker, but some devices may immediately move them to a designated cash unit. Items on the stacker will remain there until the current cash-in transaction is either cancelled by the CashAcceptor.CashInRollback command or confirmed by the CashAcceptor.CashInEnd command. These commands will cause any level 2 or level 3 items on the cash-in stacker to be moved to the appropriate cash unit. If there is no cash-in stacker then this command will move items directly to the cash units and the CashAcceptor.CashInRollback command will not be supported. Cash unit information will be updated accordingly whenever notes are moved to a cash unit during this command.
Note that the acceptor status field may change value during a cash-in transaction. If media has been retained to cash units during a cash-in transaction, it may mean that acceptor is set to stop, which means subsequent cash-in operations may not be possible. In this case, the subsequent command fails with error code CashUnitError.
The shutterControl field of the capabilites structure returned from the Common.Capabilities query will determine whether the shutter is controlled implicitly by this command or whether the client must explicitly open and close the shutter using the OpenShutter and CloseShutter commands, or the CashAcceptor.PresentMedia command. If shutterControl is FALSE then this command does not operate the shutter in any way, the client is responsible for all shutter control. If shutterControl is TRUE this command opens the shutter at the start of the command and closes it once bills are inserted.
The presentControl field of the positionCapabilities structure returned from the CashAcceptor.PositionCapabilities query will determine whether or not it is necessary to call the CashAcceptor.PresentMedia command in order to move items to the output position. If presentControl is TRUE then all items are moved immediately to the correct output position for removal (a OpenShutter command will be needed in the case of explicit shutter control). If presentControl is FALSE then items are not returned immediately and must be presented to the correct output position for removal using the CashAcceptor.PresentMedia command.
It is possible that a device may divide bill or coin accepting into a series of sub-operations under hardware control. In this case a CashAcceptor.SubCashIn event may be sent after each sub-operation, if the hardware capabilities allow it.
Returning items (single bunch):
If shutterControl is TRUE, and a single bunch of items is returned then this command will complete once the notes have been returned. A CashAcceptor.ItemsPresented event will be generated.
If shutterControl is FALSE, and a single bunch of items is returned then this command will complete without generating a CashAcceptor.ItemsPresented event, instead the CashAcceptor.ItemsPresented event will be generated by the subsequent OpenShutter or CashAcceptor.PresentMedia command.
Returning items (multiple bunches):
It is possible that a device will in certain situations return refused items in multiple bunches. In this case, this command will not complete until the final bunch has been presented and after the last CashAcceptor.ItemsPresented event has been generated. For these devices shutterControl and presentControl fields of the Capabilities / positionCapabilities structure returned from the Common.Capabilities / CashAcceptor.PositionCapabilities query must both be TRUE otherwise it will not be possible to return multiple bunches. Additionally it may be possible to request the completion of this command with a Cancel before the final bunch is presented so that after the completion of this command the CashAcceptor.Retract or CashAcceptor.Reset command can be used to move the remaining bunches, although the ability to do this will be hardware dependent.
Mixed Media Mode: If the device is operating in Mixed Media mode (Status mixedMode == mixedMdeia) the Service Provider will not perform any operation unless the ItemProcessor.MediaIn command is called or has already been called on the ItemProcesspr interface.
Exchange: This command can be used during an Exchange (exchangeType == depositInto) to accept items from the input position.
Command Message
Completion Message
Event Messages
- CashManagement.CashUnitErrorEvent
- CashAcceptor.InputRefuseEvent
- CashManagement.NoteErrorEvent
- CashAcceptor.SubCashInEvent
- CashAcceptor.ItemsInsertedEvent
- CashAcceptor.ItemsTakenEvent
- CashAcceptor.ItemsPresentedEvent
- CashManagement.InfoAvailableEvent
- CashAcceptor.InsertItemsEvent
- CashManagement.CashUnitThresholdEvent
- CashAcceptor.ShutterStatusChangedEvent
6.2.12 - CashAcceptor.CashInEnd
This command ends a cash-in transaction. If cash items are on the stacker as a result of a CashAcceptor.CashIn command these items are moved to the appropriate cash units.
The cash-in transaction is ended even if this command does not complete successfully.
Mixed Media Mode:
If the device is operating in Mixed Media mode (Status mixedMode == mixedMedia) non-cash items, e.g. checks may be moved to an output position or media bin specified by the ItemProcesoor interface. Additionally, the Service will not perform any operation unless the ItemProcessor.MediaInEnd command is called or has already been called on the ItemProcessor. Alternatively, if Capabilities mixedDepositAndRollback is TRUE, then the ItemProcessor.MediaInRollback command could be used instead of the ItemProcessor.MediaInEnd command in order to deposit the bills and return the checks.
Where ItemProcessor items may be presented the presentControl field of the positionCapabilities structure returned from the CashAcceptor.PositionCapabilities query will determine whether or not it is necessary to call the CashAcceptor.PresentMedia command in order to move items to the output position. If presentControl is TRUE then all items are moved immediately to the correct output position for removal. If presentControl is FALSE then items are not returned immediately and must be presented to the correct output position for removal using the CashAcceptor.PresentMedia command.
Exchange: This command can be used during an Exchange (exchangeType == depositInto) to deposit items accepted from the input position.
Command Message
Completion Message
Event Messages
6.2.13 - CashAcceptor.CashInRollback
This command is used to roll back a cash-in transaction. It causes all the cash items cashed in since the last CashAcceptor.CashInStart command to be returned to the customer.
This command ends the current cash-in transaction. The cash-in transaction is ended even if this command does not complete successfully.
The shutterControl field of the Capabilities structure returned from the Common.Capabilities query will determine whether the shutter is controlled implicitly by this command or whether the client must explicitly control the shutter using the OpenShutter and CloseShutter commands, or CashAcceptor.PresentMedia command. If shutterControl is FALSE then this command does not operate the shutter in any way, the client is responsible for all shutter control. If shutterControl is TRUE then this command opens the shutter and it is closed when all items are removed.
The presentControl field of the positionCapabilities structure returned from the CashAcceptor.PositionCapabilities query will determine whether or not it is necessary to call the CashAcceptor.PresentMedia command in order to move items to the output position. If presentControl is TRUE then all items are moved immediately to the correct output position for removal (a OpenShutter command will be needed in the case of explicit shutter control). If presentControl is FALSE then items are not returned immediately and must be presented to the correct output position for removal using the CashAcceptor.PresentMedia command.
Items are returned in a single bunch or multiple bunches in the same way as described for the CashAcceptor.CashIn command.
Mixed Media Mode: If the device is operating in Mixed Media mode (Status mixedMode == mixedMedia) the Service will not perform any operation unless the ItemProcesspr.MediaInRollback command is called or has already been called on the ItemProcesspr interface. Alternatively, if the Capabilities mixedDepositAndRollback is TRUE, then the ItemProcessor.MediaInEnd command could be used instead of the ItemProcessor.MediaInRollback command in order to deposit the checks and return the items.
Exchange: This command can be used during an Exchange (exchangeType == depositInto) to return items accepted from the input position. Note that ExchangeActive would not be generated in this case.
Command Message
Completion Message
Event Messages
6.2.14 - CashAcceptor.Retract
This command retracts items from an output position or internal areas within the device. Retracted items will be moved to either a retract bin, a reject bin, cash-in/recycle cash units, the transport or an intermediate stacker area. If items from internal areas within the device are preventing items at an output position from being retracted then the items from the internal areas will be retracted first. When the items are retracted from an output position the shutter is closed automatically, even if the shutterControl capability is set to FALSE.
This command terminates a running cash-in transaction. The cash-in transaction is terminated even if this command does not complete successfully.
Mixed Media Mode:
If the device is operating in Mixed Media mode (Status mixedMode == mixedMedia) this command will not perform any operation unless the ItemProcessor.RetractMedia command is called or has already been called on the ItemProcessor interface. Where the parameters for this command and the corresponding ItemProcessor.RetractMedia command conflict, for example the device is physically unable to satisfy both commands, the CashAcceptor.Retract input parameters will be used for all items.
Exchange: This command can be used during an Exchange (exchangeType == depositInto) to retract items. Note that an ExchangeActive error would not be generated in this case.
Command Message
Completion Message
Event Messages
6.2.15 - CashAcceptor.OpenShutter
This command opens the shutter. In cases where multiple bunches are to be returned under explicit shutter control and the first bunch has already been presented and taken and the output position is empty, this command moves the next bunch to the output position before opening the shutter -- see sections 8.6 and 8.7. This does not apply if the output position is not empty, for example if items had been re-inserted or dropped back into the output position as the shutter closed.
Command Message
Completion Message
Event Messages
6.2.16 - CashAcceptor.CloseShutter
This command closes the shutter.
Command Message
Completion Message
Event Messages
6.2.17 - CashAcceptor.Reset
This command is used by the client to perform a hardware reset which will attempt to return the device to a known good state. This command does not over-ride a lock obtained on another client or service handle.
If a cash-in transaction is active, this command will end it (even if this command does not complete successfully). If an exchange state is active then this command will end the exchange state (even if this command does not complete successfully).
Persistent values, such as counts and configuration information are not cleared by this command.
The device will attempt to move any items found anywhere within the device to the position specified within the resetIn parameter. This may not always be possible because of hardware problems.
If items are found inside the device one or more CashAcceptor.MediaDetected events will be generated to inform the client where the items have actually been moved to.
The shutterControl field of the Capabilities structure returned from the Common.Capabilities query will determine whether the shutter is controlled implicitly by this command or whether the client must explicitly control the shutter using the OpenShutter and CloseShutter commands, or the CashAcceptor.PresentMEdia command. If shutterControl is FALSE then this command does not operate the shutter in any way, the client is responsible for all shutter control. If shutterControl is TRUE then this command operates the shutter as necessary so that the shutter is closed after the command completes successfully and any items returned to the customer have been removed.
The presentControl field of the positionCapabilities structure returned from the CashAcceptor.PositionCapabilities query will determine whether or not it is necessary to call the CashAcceptor.PresentMedia command in order to move items to the output position. If presentControl is TRUE then all items are moved immediately to the correct output position for removal (a OpenShutter command will be needed in the case of explicit shutter control). If presentControl is FALSE then items are not returned immediately and must be presented to the correct output position for removal using the CashAcceptor.PresentMedia command.
If requested, items are returned in a single bunch or multiple bunches in the same way as described for the CashAcceptor.CashIn command.
Mixed Media Mode:
The value of Status mixedMode is not changed by this command. Where the items are to be moved to a cash unit, the cash unit must support an itemType of "itemProcessor".
Command Message
Completion Message
Event Messages
6.2.18 - CashAcceptor.ConfigureNotetypes
This command is used to configure the note types the banknote reader should accept during cash-in. All note types the banknote reader should accept must be given in the input structure. If an unknown note type is given the error code "unsupportedData" will be returned. The values set by this command are persistent.
Command Message
Completion Message
Event Messages
None6.2.19 - CashAcceptor.CreateP6Signature
This command is used to create a reference signature (normally a level 3 note) that was checked and regarded as a forgery. The reference can be compared with the available signatures of the cash-in transactions to track back the customer.
When this command is executed, the device waits for a note to be inserted at the input position, transports the note to the recognition module, creates the signature and then returns the note to the output position.
The shutterControl field of the capabilities structure returned from the Common.Capabilities query will determine whether the shutter is controlled implicitly by this command or whether the client must explicitly control the shutter using the OpenShutter and CloseShutter commands, or CashAcceptor.PresentMedia command. If shutterControl is FALSE then this command does not operate the shutter in any way, the client is responsible for all shutter control. If shutterControl is TRUE then this command opens and closes the shutter at various times during the command execution and the shutter is finally closed when all items are removed.
The presentControl field of the positionCapabilities structure returned from the CashAcceptor.PositionCapabilities query will determine whether or not it is necessary to call the CashAcceptor.PresentMedia command in order to move items to the output position. If presentControl is TRUE then all items are moved immediately to the correct output position for removal (a OpenShutter command will be needed in the case of explicit shutter control). If presentControl is FALSE then items are not returned immediately and must be presented to the correct output position for removal using the CashAcceptor.PresentMedia command.
On devices with implicit shutter control, the InsertItems event will be generated when the device is ready to start accepting media.
The client may have to execute this command repeatedly to make sure that all possible signatures are captured.
If a single note is entered and returned to the customer but cannot be processed fully (e.g. no recognition software in the recognition module, the note is not recognized, etc.) then a InputRefuse event will be sent and the command will complete. In this case, the output parameters will be set as follows, noteId = zero, length = zero, orientation = "unknown" and signature = NULL.
Command Message
Completion Message
Event Messages
6.2.20 - CashAcceptor.ConfigureNoteReader
This command is used to configure the currency description configuration data into the banknote reader module. The format and location of the configuration data is vendor and/or hardware dependent.
Command Message
Completion Message
Event Messages
None6.2.21 - CashAcceptor.CompareP6Signature
This command is used to compare the signatures of a reference banknote with the available signatures of the cash-in transactions.
The reference signatures are created by the CashAcceptor.CreateP6Signature command.
The transaction signatures are obtained through the CashAcceptor.GetP6Signature command.
The signatures (1 to 4) of the reference banknote are typically the signatures of the 4 orientations of the banknote.
The CashAcceptor.CompareP6Signature command may return a single indication or a list of indications to the matching signatures, each one associated to a confidence level factor. If the Service Provider does not support the confidence level factor, it returns a single indication to the best matching signature with the confidence level factor set to zero.
If the comparison completed with no matching signatures found then the command returns "ok" with p6SignaturesIndex empty.
This command must be used outside of the cash-in transactions and outside of exchange states.
Command Message
Completion Message
Event Messages
None6.2.22 - CashAcceptor.Replenish
This command replenishes items from a single cash unit to multiple cash units. Clients can use this command to ensure that there is the optimum number of items in the cassettes by moving items from a source cash unit to a target cash unit. This is especially applicable if a replenishment cash unit is used for the replenishment and can help to minimize manual replenishment operations.
The CashAcceptor.ReplenishTarget command can be used to determine what cash units can be specified as target cash units for a given source cash unit. Any items which are removed from the source cash unit that are not of the correct currency ID and value for the target cash unit during execution of this command will be returned to the source cash unit.
The count, cashInCount, dispensedCount and rejectCount returned with the CashManagement.CashUnitInfo command will be updated as part of the execution of this command.
If the command fails after some items have been moved, the command will complete with an appropriate error code, and a CashAcceptor.IncompleteReplenishEvent will be sent.
Command Message
Completion Message
Event Messages
6.2.23 - CashAcceptor.SetCashInLimit
This command specifies the amount/number of items limitation for the current cash-in transaction. This command can only be called after the CashAcceptor.CashInStart command and before the first CashAcceptor.CashIn command, otherwise it will fail with the SequenceError error. Any command that completes the cash-in transaction (i.e. CashAcceptor.CashInEnd, CashAcceptor.CashInRollback, CashAcceptor.Retract and CashAcceptor.Reset commands) will clear the limit.
This limit is active until the end of the current cash-in transaction. The use of this command is optional, however it needs to be called for each cash-in transaction that needs a limitation.
This command does not disable/enable the recognition of individual note types. The CashAcceptor.ConfigureNotetypes command must be used to refuse a certain note type during cash-in transactions.
If "limitMultiple" is specified in the cashInLimit capability, the command may be called multiple times to add to or override amount limits placed on the current cash-in transaction; the input parameter descriptions below define whether limits are added or overridden. If "limitMultiple" is not specified, this command can only be called once per cash-in transaction otherwise it will fail with the SequenceError error.
Command Message
Completion Message
Event Messages
None6.2.24 - CashAcceptor.CashUnitCount
This command counts the items in the cash unit(s). If it is necessary to move items internally to count them, the items should be returned to the cash unit from which they originated before completion of the command. If items could not be moved back to the cash unit they originated from and did not get rejected, the command will complete with an appropriate error.
During the execution of this command one CashManagement.CashUnitInfoChangedEvent will be generated for each cash unit that has been counted successfully, or if the counts have changed, even if the overall command fails.
After completion of this command the number of items rejected can be determined by calling the CashManagement.CashUnitInfo command and checking the value of the rejectCount field within the output structure. The rejectCount value is incremented by one for each item rejected during execution of this command.
This command is designed to be used on devices where the count cannot be guaranteed to be accurate and therefore may need to be automatically counted periodically. Upon successful completion, for those cash units that have been counted, the count field is accurately reported with the CashManagement.CashUnitInfo command.
Command Message
Completion Message
Event Messages
6.2.25 - CashAcceptor.DeviceLockControl
This command can be used to lock or unlock a CashAcceptor device, it can also be used to lock or unlock one or more cash units.
During normal device operation the device and cash units will be locked and removal will not be possible. If supported the device or cash units can be unlocked, ready for removal. In this situation the device will still remain online and cash-in or dispense operations will be possible, as long as the device or cash units are not physically removed from their normal operating position.
If the lock action is specified and the device or cash units are already locked, or if the unlock action is specified and the device or cash units are already unlocked then the action will complete successfully.
Once a cash unit has been removed and reinserted it will then have a "manualInsertion" status. This status can only be cleared by issuing a CashManagement.StartExchange/CashManagement.EndExchange command sequence.
The device and all cash units will also be locked implicitly as part of the execution of the CashManagement.EndExchange or the CashAcceptor.Reset command.
Command Message
Completion Message
Event Messages
6.2.26 - CashAcceptor.SetMode
This command is used to set the deposit mode for the device and is only applicable for Mixed Media processing. The deposit mode determines how the device will process non cash items that are inserted. The deposit mode applies to all subsequent transactions. The deposit mode is persistent and is unaffected by a device reset by CashDispenser.Reset or reset on another interface. The command will fail with a InvalidData error where an attempt is made to set a mode that is not supported.
Command Message
Completion Message
Event Messages
None6.2.27 - CashAcceptor.PresentMedia
This command opens the shutter and presents items to be taken by the customer. The shutter is automatically closed after the media is taken. The command can be called after a CashAcceptor.CashIn, CashAcceptor.CashInRollback, CashAcceptor.Reset or CashAcceptor.CreateP6Signature command and can be used with explicit and implicit shutter control. The command is only valid on positions where usage reported by the CashAcceptor.PositionCapabilities command is "rollback" or "refuse" and where presentControl reported by the CashAcceptor.PositionCapabilities command is FALSE.
This command cannot be used to present items stacked through the CashDispenser interface. Where this is attempted the command fails with a SequenceError error.
Mixed Media Mode:
If the device is operating in Mixed Media mode (Status mixedMode == "mixedMedia") this command will not perform any operation unless the ItemProcessor.PresentMedia command is called or has already been called on the ItemProcessor interface. Shutter control on devices that support Mixed Media processing is always implicit.
Command Message
Completion Message
Event Messages
6.2.28 - CashAcceptor.Deplete
This command removes items from multiple cash units to a single cash unit. Clients can use this command to ensure that there is the optimum number of items in the cassettes by moving items from source cash units to a target cash unit. This is especially applicable if surplus items are removed from multiple recycle cash units to a replenishment cash unit and can help to minimize manual replenishment operations.
The CashAcceptor.DepleteSource command can be used to determine what cash units can be specified as source cash units for a given target cash unit.
The count, cashInCount, dispensedCount and rejectCount returned with the CashManagement.CashUnitInfo command will be updated as part of the execution of this command.
If the command fails after some items have been moved, the command will complete with an appropriate error code, and a CashAcceptor.IncompleteDepleteEvent event will be sent.
Command Message
Completion Message
Event Messages
6.2.29 - CashAcceptor.PreparePresent
In cases where multiple bunches are to be returned under explicit shutter control, this command is used for the purpose of moving a remaining bunch to the output position explicitly before using the following commands:
OpenShutter
CashAcceptor.PresentMedia
The client can tell whether the additional items were left by using CashAcceptor.PresentStatus command. This command does not affect the status of the current cash-in transaction.
Command Message
Completion Message
Event Messages
6.3 - Event Messages
6.3.1 - CashManagement.CashUnitErrorEvent
This event is generated if there is a problem with a cash unit during the execution of a command.
6.3.2 - CashAcceptor.InputRefuseEvent
This event specifies that the device has refused either a portion or the entire amount of the cash-in order.
6.3.3 - CashManagement.NoteErrorEvent
This event specifies the reason for a note detection error during the execution of a command.
6.3.4 - CashAcceptor.SubCashInEvent
This event is generated when one of the sub cash-in operations into which the cash-in operation was divided has finished successfully.
6.3.5 - CashManagement.InfoAvailableEvent
This execute event is generated when information is available for items detected during the cash processing operation.
6.3.6 - CashAcceptor.InsertItemsEvent
This event notifies the client when the device is ready for the user to insert items.
6.3.7 - CashManagement.CashUnitThresholdEvent
This user event is generated when a threshold condition has occurred in one of the cash units.
This event can be triggered either by hardware sensors in the device or by the count reaching the minimum or maximum value as specified in the GetCashUnitInfo structure.
The client can check if the device has hardware sensors by querying the hardwareSensor field of the cash unit structure. If a cash unit has this capability then threshold events based on hardware sensors will be triggered if the maximum or minimum values are not used or are set to zero.
6.3.8 - CashManagement.CashUnitInfoChangedEvent
This service event is generated under the following circumstances:
-
It is generated whenever status changes. For instance, a cash unit has been removed or inserted, or a cash unit has become empty or full.
-
This event will also be generated for every cash unit changed in any way (including changes to counts, e.g. count, rejectCount, initialCount, dispensedCount and presentedCount) as a result of the CashManagement.SetCashUnitInfo command.
-
This event will also be fired when any change is made to a cash unit by the following commands, except for changes to counts (e.g. count, rejectCount, initialCount, dispensedCount and presentedCount):
- In addition this event will be generated when a cash unit has been counted during the CashAcceptor.CashUnitCount command execution.
When a cash unit is removed, the status of the cash
unit becomes missing.
If a new cash unit is inserted the cash unit structure reported by the last CashManagement.GetCashUnitInfo command is no longer valid. In that case a client should issue a CashManagement.GetCashUnitInfo command after receiving this event to obtain updated cash unit information.
6.3.9 - CashAcceptor.IncompleteReplenishEvent
This event is generated when some items had been moved before the CashAcceptor.Replenish command failed with an error code (not "success"), but some items were moved then the details will be reported with this event. This event can only occur once per command.
6.3.10 - CashAcceptor.IncompleteDepleteEvent
This execute event is generated when some items had been moved before the CashAcceptor.Deplete command failed with an error code (not "success"), but some items were moved. In this case the details will be reported with this event. This event can only occur once per command.
6.4 - Unsolicited Messages
6.4.1 - CashAcceptor.ItemsTakenEvent
This service specifies that items presented to the user have been taken. This event may be generated at any time.
6.4.2 - CashAcceptor.ItemsPresentedEvent
This service event specifies that items have been presented to the output position, and the shutter has been opened to allow the user to take the items.
6.4.3 - CashAcceptor.ItemsInsertedEvent
This service event specifies that items have been inserted into the cash-in position by the user. This event may be generated at any time.
6.4.4 - CashAcceptor.MediaDetectedEvent
This service event is generated if media is detected during a CashAcceptor.Reset command. The parameter on the event specifies the position of the media on completion of the reset. If the device has been unable to successfully move the items found then this parameter will be omitted.
6.4.5 - CashAcceptor.ShutterStatusChangedEvent
Within the limitations of the hardware sensors this service event is generated whenever the status of a shutter changes. The shutter status can change because of an explicit, implicit or manual operation depending on how the shutter is operated.
6.4.6 - CashAcceptor.CountAccuracyChangedEvent
This event is generated when information about the accuracy of count of a cash unit is changed.
7 - Key Management Interface
This chapter defines the Key Management interface functionality and messages.
7.1 - Summary
This section describes the general interface for the following functions:
-
Loading of encryption keys
-
EMV 4.0 PIN blocks, EMV 4.0 public key loading, static and dynamic data verification
Important Notes:
-
This revision of this specification does not define all key management procedures; some key management is still vendor-specific.
-
Key space management is customer-specific, and is therefore handled by vendor-specific mechanisms.
Key values are passed to the API as binary hexadecimal values, for example: 0123456789ABCDEF = 0x01 0x23 0x45 0x67 0x89 0xAB 0xCD 0xEF. When hex values are passed to the API within strings, the hex digits 0xA to 0xF can be represented by characters in the ranges ‘a’ to ‘f’ or ‘A’ to ‘F’. The following commands and events were initially added to support the German ZKA standard, but may also be used for other national standards:
Certain levels of the PCI EPP security standards specify that if a key encryption key is deleted or replaced, then all keys in the hierarchy under that key encryption key are also removed. Key encryption keys have the keyEncKey type of access. Clients can check impact of key deletion using Keydetail.
7.2 - General Information
7.2.1 - RKL Terminology
This section provides extended explanation of concepts and functionality needing further clarification. The terminology as described below is used within the following sections.
| Definitions and Abbreviations | |
|---|---|
| ATM | Automated Teller Machine, used here for any type of self-service terminal, regardless whether it actually dispenses cash |
| CA | Certificate Authority |
| Certificate | A data structure that contains a public key and a name that allows certification of a public key belonging to a specific individual. This is certified using digital signatures. |
| HOST | The remote system that an ATM communicates with. |
| KTK | Key Transport Key |
| PKI | Public Key Infrastructure |
| Private Key | That key of an entity’s key pair that should only be used by that entity. |
| Public Key | That key of an entity’s key pair that can be made public. |
| Symmetric Key | A key used with symmetric cryptography |
| verification Key | A key that is used to verify the validity of a certificate |
| signatureIssuer | An entity that signs the ATM´s public key at production time, may be the ATM manufacturer |
| Notation of Cryptographic Items and Functions | |
|---|---|
| SKE | The private key belonging to entity E |
| PKE | The public belonging to entity E |
| SKATM | The private key belonging to the ATM/PIN |
| PKATM | The public key belonging to the ATM/PIN |
| SKHOST | The private key belonging to the Host |
| PKHOST | The public key belonging to the Host |
| SKSI | The private key belonging to Signature Issuer |
| PKSI | The public key belonging to Signature Issuer |
| SKROOT | The root private key belonging to the Host |
| PKROOT | The root public key belonging to the Host |
| KNAME | A symmetric key |
| CertHOST | A Certificate that contains the public verification of the host and is signed by a trusted Certificate Authority. |
| CertATM | A Certificate that contains the ATM/PIN public verification or encipherment key, which is signed by a trusted Certificate Authority. |
| CertCA | The Certificate of a new Certificate Authority |
| RATM | Random Number of the ATM/PIN |
| IHOST | Identifier of the Host |
| KKTK | Key Transport Key |
| RHOST | Random number of the Host |
| IATM | Identifier of the ATM/PIN |
| TPATM | Thumb Print of the ATM/PIN |
| Sign(SKE)[D] | The signing of data block D, using the private key SKE |
| Recover(PKE)[S] | The recovery of the data block D from the signature S, using the private key PKE |
| RSACrypt(PKE)[D] | RSA Encryption of the data block D using the public key PKE |
| Hash [M] | Hashing of a message M of arbitrary length to a 20 Byte hash value |
| Des(K) [D] | DES encipherment of an 8 byte data block D using the secret key K |
| Des-1(K)[D] | DES decipherment of an 8 byte data block D using the 8 byte secret key K |
| Des3(K)[D] | Triple DES encipherment of an 8 byte data block D using the 16 byte secret key K = (KL |
| Des3-1 (K) [D] | Triple DES decipherment of an 8 byte data block D using the 16 byte secret key K = (KL |
| RndE | A random number created by entity E |
| UIE | Unique Identifier for entity E |
| ( A || B ) | Concatenation of A and B |
7.2.2 - Remote Key Loading Using Signatures
RSA Data Authentication and Digital Signatures
Digital signatures rely on a public key infrastructure (PKI). The PKI model involves an entity, such as a Host, having a pair of encryption keys – one private, one public. These keys work in consort to encrypt, decrypt and authenticate data. One way authentication occurs is through the client of a digital signature. For example:
- The Host creates some data that it would like to digitally sign;
- Host runs the data through a hashing algorithm to produce a hash or digest of the data. The digest is unique to every block of data – a digital fingerprint of the data, much smaller and therefore more economical to encrypt than the data itself.
- Digest is encrypted with the Host’s private key.
This is the digital signature – a data block digest encrypted with the private key. The Host then sends the following to the ATM:
- Data block.
- Digital signature.
- Host’s public key.
To validate the signature, the ATM performs the following:
- ATM runs data through the standard hashing algorithm – the same one used by the Host – to produce a digest of the data received. Consider this digest2;
- ATM uses the Host’s public key to decrypt the digital signature. The digital signature was produced using the Host’s private key to encrypt the data digest; therefore, when decrypted with the Host’s public key it produces the same digest. Consider this digest1. Incidentally, no other public key in the world would work to decrypt digest1 – only the public key corresponding to the signing private key.
- ATM compares digest1 with digest2.
If digest1 matches digest2 exactly, the ATM has confirmed the following:
• Data was not tampered with in transit. Changing a single bit in the data sent from the Host to the ATM would cause digest2 to be different than digest1. Every data block has a unique digest; therefore, an altered data block is detected by the ATM.
• Public key used to decrypt the digital signature corresponds to the private key used to create it. No other public key could possibly work to decrypt the digital signature, so the ATM was not handed someone else’s public key. This gives an overview of how Digital Signatures can be used in Data Authentication. In particular, Signatures can be used to validate and securely install Encryption Keys. The following section describes Key Exchange and the use of Digital signatures.
RSA Secure Key Exchange using Digital Signatures
In summary, both end points, the ATM and the Host, inform each other of their Public Keys. This information is then used to securely send the PIN device Master Key to the ATM. A trusted third party, the Signature Issuer, is used to generate the signatures for the Public keys of each end point, ensuring their validity.
The detail of this is as follows:
Purpose: The Host wishes to install a new master key (KM) on the ATM securely.
Assumptions:
-
The Host has obtained the Public Key (PK SI ) from the Signature Issuer.
-
The Host has provided the Signature Issuer with its Public Key (PK HOST ), and receives the corresponding signature Sign(SK SI )[ PK HOST ]. The Signature Issuer uses its own Private Key (SK SI ) to create this signature.
-
In the case where Enhanced Remote Key Loading is used, the host has provided the Signature Issuer with its Public Key (PK ROOT ), and receives the corresponding signature Sign(SK SI )[PK ROOT ]. The host has generated another key pair PKHOST and SKHOST and signs the PKHOST with the SKROOT.
-
(Optional) The host obtains a list of the valid encryption module's Unique Identifiers. The Signature Issuer installs a Signature Sign(SK SI )[ UI ATM ] for the Unique Id (UI ATM ) on the ATM encryption module. The Signature Issuer uses SKSI to do this.
-
The Signature Issuer installs its Public Key (PK SI ) on the ATM encryption module. It also derives and installs the Signature Sign(SK SI )[PK ATM ] of the ATM encryption module's Public Key (PK ATM ) on the ATM encryption module. The Signature Issuer uses SKSI to do this.
-
The ATM encryption module additionally contains its own Public (PK ATM ) and Private Key (SK ATM ).
Step 1
The ATM KeyManagement sends its Public Key to the Host in a secure structure:
The ATM KeyManagement sends its ATM Public Key with its associated Signature. When the Host receives this information it will use the Signature Issuer’s Public Key to validate the signature and obtain the ATM Public Key.
The command used to export the encryption module's public key securely as described above is KeyManagement.ExportRsaIssuerSignedItem..
Step 2 (Optional)
The Host verifies that the key it has just received is from a valid sender.
It does this by obtaining the encryption module unique identifier. The ATM KeyManagement sends its Unique Identifier with its associated Signature. When the Host receives this information it will use the Signature Issuer’s Public Key to validate the signature and retrieve the Encryption Module Unique Identifier. It can then check this against the list it received from the Signature Issuer.
The command used to export the encryption module Unique Identifier is KeyManagement.ExportRsaIssuerSignedItem.
Step 3 (Enhanced Remote Key Loading only)
The Host sends its root public key to the ATM KeyManagement:
The Host sends its Root Public Key (PKROOT) and associated Signature. The ATM encryption module verifies the signature using PKSI and stores the key.
The command used to import the host root public key securely as described above is ImportRsaPublicKey.
Step 4
The Host sends its public key to the ATM KeyManagement:
The Host sends its Public Key (PK HOST ) and associated Signature. The ATM encryption module verifies the signature using PKSI (or PKROOT in the Enhanced Remote Key Loading Scheme) and stores the key.
The command used to import the host public key securely as described above is ImportRsaPublicKey.
Step 5
The ATM KeyManagement receives its Master Key from the Host:
The Host encrypts the Master Key (KM) with PKATM. A signature for this is then created using SKHOST. The ATM encryption module will then validate the signature using PKHOST and then obtain the master key by decrypting using SKATM.
The commands used to exchange master symmetric keys as described above are:
• KeyManagement.StartKeyExchage
• ImportRsaSignedDesKey
Step 6 – Alternative including random number The host requests the ATM KeyManagement to begin the DES key transfer process and generate a random number.
The Host encrypts the Master Key (KM) with PKATM. A signature for the random number and encrypted key is then created using SKHOST.
The ATM encryption module will then validate the signature using PKHOST, verify the random number and then obtain the master key by decrypting using SKATM.
The commands used to exchange master symmetric keys as described above are:
• KeyManagement.StartKeyExchage
• ImportRsaSignedDesKey
The following diagrams summaries the key exchange process described above:
Default Keys and Security Item loaded during manufacture
Several keys and a security item which are mandatory for the 2 party/Signature authentication scheme are installed during manufacture. These items are given fixed names so multi-vendor clients can be developed without the need for vendor specific configuration tools.
| Item Name | Item Type | Signed by | Description |
|---|---|---|---|
| “sigIssuerVendor” | Public Key | N/A | The public key of the signature issuer, i.e. PKSI |
| “eppCryptKey” | Public/Private key-pair | The private key associated with sigIssuerVendor | The key-pair used to encrypt and encrypt the symmetric. key, i.e SK ATM and PK ATM . The public key is used for encryption by the host and the private for decryption by the epp. |
In addition the following optional keys can be loaded during manufacture.
| Item Name | Item Type | Signed by | Description |
|---|---|---|---|
| “eppSignKey” | Public/Private key-pair | The private key associated with sigIssuerVendor | A key-pair where the private key is used to sign data, e.g. other generated key pairs |
7.2.3 - Initialization Phase – Signature Issuer and ATM PIN
This would typically occur in a secure manufacturing environment.
7.2.4 - Initialization Phase – Signature Issuer and Host
This would typically occur in a secure offline environment.
7.2.5 - Key Exchange – Host and ATM PIN
This following is a typical interaction for the exchange of the initial symmetric master key in a typical ATM Network. The following is the recommended sequence of interchanges.
7.2.6 - Key Exchange (with random number) – Host and ATM PIN
This following is a typical interaction for the exchange of the initial symmetric master key when the PIN device Service Provider supports the KeyManagement.StartKeyExchange command.
7.2.7 - Enhanced RKL, Key Exchange (with random number) – Host and ATM PIN
This following is a typical interaction for the exchange of the initial symmetric master key when the PIN device and Service Provider supports the Enhanced Signature Remote Key Loading scheme.
7.2.8 - Remote Key Loading Using Certificates
The following sections demonstrate the proper usage of the CEN KeyManagement interface to accomplish Remote Key Loading using Certificates. There are sequence diagrams to demonstrate how the CEN KeyManagement interface can be used to complete each of the TR34 operations.
7.2.9 - Certificate Exchange and Authentication
In summary, both end points, the ATM and the Host, inform each other of their Public Keys. This information is then used to securely send the PINS device Master Key to the ATM. A trusted third party, Certificate Authority (or a HOST if it becomes the new CA), is used to generate the certificates for the Public Keys of each end point, ensuring their validity. NOTE: The KeyManagement.LoadCertificate and KeyManagement.GetCertificate do not necessarily need to be called in the order below. This way though is the recommend way.
The following flow is how the exchange authentication takes place:
• KeyManagement.LoadCertificate is called. In this message contains the host certificate, which has been signed by the trusted CA. The encryptor uses the Public Key of the CA (loaded at the time of production) to verify the validity of the certificate. If the certificate is valid, the encryptor stores the HOST’s Public Verification Key.
• Next, KeyManagement.GetCertificate is called. The encryptor then sends a message that contains a certificate, which is signed by the CA and is sent to the HOST. The HOST uses the Public Key from the
CA to verify the certificate. If valid then the HOST stores the encryptor’s verification or encryption key
(primary or secondary this depends on the state of the encryptor).
The following diagram shows how the Host and ATM Load and Get each other’s information to make Remote Key Loading possible:
7.2.10 - Remote Key Exchange
After the above has been completed, the HOST is ready to load the key into the encryptor. The following is done to
complete this and the client must complete the Remote Key Exchange in this order:
-
First, the Keymanagement.StartKeyExchange is called. This returns RATM from the encryptor to be used in the authenticating the ImportRSAEnchiperdPKCS7Key message.
-
Next, ImportRSAEnchiperdPKCS7Key is called. This command sends down the KTK to the encryptor. The following items below show how this is accomplished.
a) HOST has obtained a Key Transport Key and wants to transfer it to the encryptor. HOST constructs a key block containing an identifier of the HOST, IHOST, and the key, KKTK, and enciphers the block,using the encryptor’s Public Encryption Key from the KeyManagement.GetCertificate command.b) After completing the above, the HOST generates random data and builds the outer message containing the random number of the host, RHOST, the random number of the encryptor returned in the Keymanagement.StartKeyExchange command, RATM , the identifier of the encryptor, IENC, and the enciphered key block. The HOST signs the whole block using its private signature key and sends the message down to the encryptor.
The encryptor then verifies the HOST’s signature on the message by using the HOST’s Public Verification Key. Then the encryptor checks the identifier and the random number of the encryptor passed in the message to make sure that the encryptor is talking to the right HOST. The encryptor then deciphers the enciphered block using its private verification key. After the message has been deciphered, the encryptor checks the Identifier of the HOST. Finally, if everything checks out to this point the encryptor will load the Key Transport Key. NOTE: If one step of this verification occurs the encryptor will return the proper error to the HOST.c) After the Key Transport Key has been accepted, the encryptor constructs a message that contains the random number of the host, the random number of the encryptor and the HOST identifier all signed by the private signature key of the encryptor. This message is sent to the host.
d) The HOST verifies the message sent from the encryptor by using the ATM’s public verification key. The HOST then checks the identifier of the host and then compares the identifier in the message with the one stored in the HOST. Then checks the random number sent in the message and to the one stored in the HOST. The HOST finally checks the encryptor’s random number with the one received in received in the Keymanagement.StartKeyExchange command.
The following diagram below shows how the Host and ATM transmit the Key Transport Key.
7.2.11 - Replace Certificate
After the key is been loaded into the encryptor, the following could be completed:
- (Optional) ReplaceCertificate. This is called by entity that would like to take over the job of being the CA. The new CA requests a Certificate from the previous Certificate Authority. The HOST must over-sign the message to take over the role of the CA to ensure that the encryptor accepts the new Certificate Authority. The HOST sends the message to the encryptor. The encryptor uses the HOST’s Public Verification Key to verify the HOST’s signature. The encryptor uses the previous CA’s Public Verification Key to verify the signature on the new Certificate sent down in the message. If valid, the EPP stores the new CA’s certificate and uses the new CA’s Public Verification Key as its new CA verification key. The diagram below shows how the Host and the ATM communicate to load the new CA.
7.2.12 - Primary and Secondary Certificate
Primary and Secondary Certificates for both the Public Verification Key and Public Encipherment Key are pre-loaded into the encryptor. Primary Certificates will be used until told otherwise by the host via the KeyManagement.LoadCertificate or KeyManagement.ReplaceCertificate commands. This change in state will be specified in the pkcs #7 message of the LoadCertificate or [KeyManagement.ReplaceCertificate](#keymanagement.replacecertificate commands. The reason why the host would want to change states is because the host thinks that the Primary Certificates have been compromised.
After the host tells the encryptor to shift to the secondary certificate state, only Secondary Certificates can be used. The encryptor will no longer be able to go back to the Primary State and any attempts from the host to get or load a Primary Certificate will return an error. When either Primary or Secondary certificates are compromised it is up to the vendor on how the encryptor should be handled with the manufacturer.
7.2.13 - TR34 BIND To Host
This section defines the command to use when transferring a TR34 BIND token This step is a pre-requisite for all other TR34 operations. The PIN device must be bound to a host before any other TR34 operation will succeed. It is recommended that the encryption certificate retrieved during this process is stored for future use otherwise it will need to be requested prior to every operation.
7.2.14 - TR34 Key Transport
There are two mechanisms that can be used to transport symmetric keys under TR34; these are the One Pass and Two Pass protocols. The use of CEN commands for these two protocols are shown in the following sections. NOTE: Refer to CRKLLoadOptions in the Capabilities output structure for an indication of whether the PIN device supports one-pass and/or two-pass protocols.
One Pass
This section defines the command to use when transferring a TR34 KEY token (1-pass). Pre-condition: A successful BIND command has completed such that the KeyManagement is bound to the host.
Two Pass
This section defines the command to use when transferring a TR34 KEY token (2-pass). Pre-condition: A successful BIND command has completed such that theKEyManagement is bound to the host.
7.2.15 - TR34 REBIND To New Host
This section defines the command to use when transferring a TR34 REBIND token. Pre-condition: A successful BIND command has completed such that the KeyManagement is bound to the host.
NB: Dotted lines represent commands that are only required if the KeyManagement encryption certificate has not been previously stored by the host.
7.2.16 - TR34 Force REBIND To New Host
This section defines the command to use when transferring a TR34 Force REBIND token. Pre-condition: A successful BIND command has completed such that the KeyManagement is bound to the host.
NB: Dotted lines represent commands that are only required if the KeyManagement encryption certificate has not been previously stored by the host. Although the random number token is requested as part of this operation, it is discarded by the host and is not actually used in the Force Rebind token.
7.2.17 - TR34 UNBIND From Host
This section defines the command to use when transferring a TR34 UNBIND token. Pre-condition: A successful BIND command has completed such that the KeyManagement is bound to the host.
NB: Dotted lines represent commands that are only required if the KeyManagement encryption certificate has not been previously stored by the host
7.2.18 - TR34 Force UNBIND From Host
This section defines the command to use when transferring a TR34 Force UNBIND token. Pre-condition: A successful BIND command has completed such that the KeyManagement is bound to the host.
NB: Dotted lines represent commands that are only required if the KeyManagement encryption certificate has not been previously stored by the host. Although the random number token is requested as part of this operation, it is discarded by the host and is not actually used in the Force Unbind token.
7.2.19 - EMV Support
EMV support by this specification consists in the ability of importing Certification Authority and Chip Card Public Keys, creating the PIN blocks for offline PIN verification and verifying static and dynamic data. This section is used to further explain concepts and functionality that needs further clarification.
The PIN service is able to manage the EMV chip card regarding the card authentication and the RSA local PIN verification. Two steps are mandatory in order to reach these two functions: The loading of the keys which come from the Certification Authorities or from the card itself, and the EMV PIN block management.
The Service Provider is responsible for all key validation during the import process. The client is responsible for management of the key lifetime and expiry after the key is successfully imported
Keys loading
The final goal of a client is to retrieve the keys located on card to perform the operations of authentication or local PIN check (RSA encrypted). These keys are provided by the card using EMV certificates and can be retrieved using a Public Key provided by a Certification Authority. The client should first load the keys issued by the Certification Authority. At transaction time the client will use these keys to load the keys that the client has retrieved from the chip card.
Certification Authority keys
These keys are provided in the following formats:
- Plain text.
- Plain Text with EMV 2000 Verification Data.
- EPI CA (or self signed) format as specified in the Europay International, EPI CA Module Technical – Interface specification Version 1.4.
- pkcsV15 encrypted (as used by GIECB in France).
EPI CA format
The following table corresponds to table 4 of the Europay International, EPI CA Module Technical – Interface specification Version 1.4 and identifies the Europay Public Key (self-certified) and the associated data:
| Field Name | Length | Description | Format |
|---|---|---|---|
| ID of Certificate Subject | 5 | RID for Europay | Binar |
| Europay public key Index | 1 | Europay public key Index | Binary |
| Subject public key Algorithm Indicator | 1 | Algorithm to be used with the Europay public key Index, set to 0x01 | Binary |
| Subject public key Length | 1 | Length of the Europay public key Modulus (equal to Nca) | Binary |
| Subject public key Exponent Length | 1 | Length of the Europay public key Exponent | Binary |
| Leftmost Digits of Subject public key | Nca-37 | Nca-37 most significant bytes of the Europay public key Modulus | Binary |
| Subject public key Remainder | 37 | 37 least significant bytes of the Europay public key Modulus | Binary |
| Subject public key Exponent | 1 | Exponent for Europay public key | Binary |
| Subject public key Certificate | Nca | Output of signature algorithm | Binary |
Table 1
The following table corresponds to table 13 of the Europay International, EPI CA Module Technical – Interface specification Version 1.4 and identifies the Europay Public Key Hash code and associated data.
| Field Name | Length | Description | Format |
|---|---|---|---|
| ID of Certificate Subject | 5 | RID for Europay | Binary |
| Europay public key Index | 1 | Europay public key Index | Binary |
| Subject public key Algorithm Indicator | 1 | Algorithm to be used with the Europay public key Index, set to 0x01 | Binary |
| Certification Authority public key Check Sum | 20 | Hash-code for Europay public key | Binary |
Table 2
Table 2 corresponds to table 13 of the Europay International, EPI CA Module Technical – Interface specification Version 1.4.
Chip card keys
These keys are provided as EMV certificates which come from the chip card in a multiple layer structure (issuer key first, then the ICC keys). Two kinds of algorithm are used with these certificates in order to retrieve the keys: One for the issuer key and the other for the ICC keys (ICC Public Key and ICC PIN encipherment key). The associated data with these algorithms – The PAN (Primary Account Number) and the SDA (Static Data to be Authenticated) - come also from the chip card.
PIN Block Management
The PIN block management is done through the command GetPinBlock. A new format formEmv has been added to indicate to the PIN service that the PIN block must follow the requirements of the EMVCo, Book2 – Security & Key management Version 4.0 document The parameter customerData is used in this case to transfer to the PIN service the challenge number coming from the chip card. The final encryption must be done using a RSA Public Key. Please note that the client is responsible to send the PIN block to the chip card inside the right APDU.
SHA-1 Digest
The SHA-1 Digest is a hash algorithm used by EMV in validating ICC static and dynamic data item. The SHA-1 Digest is supported through the digest command. The client will pass the data to be hashed to the Service Provider. Once the encryptor completes the SHA-1 hash code, the Service Provider will return the 20-byte hash value back to the client.
7.2.20 - ImportKey command Input-Output Parameters
The tables in this section describe the input/output parameters for various scenarios in which the importKey command is used, compared to input/output parameters for older commands that it supercedes.
Importing a 3DES 16-byte terminal master key using signature-based remote key loading (SRKL):
For this example, the following input data is available:
Name of key to be imported = testKey
Name of the key used to decrypt the encrypted key value = eppCryptKey
Name of the key used to verify the signature = hostKey
Encrypted key value =
KeyManagement.ImportKey Input Data
| Parameter Name | Example Value |
|---|---|
| key | testKey |
| decryptKey | eppCryptKey |
| rsaEnchiperAlgorithm | oaep |
| value | <encrypted key value> |
| use | keyEncKey |
| sigKey | hostKey |
| rsaSignatureAlgorithm | pss |
| signature | <signature generated by the host> |
For this example, the following output data is expected:
Key Check Mode = kcv zero
Key Check Value =
KeyManagement.ImportKey Output Data
| Parameter Name | Example Value |
|---|---|
| keyLength | double |
| keyCheckMode | zero |
| keyCheckValue | <key check value> |
KeyManagement.ImportKey Input Data
| Parameter Name | Example Value |
|---|---|
| key | testKey |
| keyAttributes.keyUsage | ‘K0’ |
| keyAttributes.algorithm | ‘T’ |
| keyAttributes.modeOfUse | ‘D’ |
| keyAttributes.cryptoMethod | 0 |
| value | <encrypted key value> |
| decryptKey | eppCryptKey |
| decryptMethod | rsaesOaep |
| verificationData | <signature generated by the host> |
| verifyKey | hostKey |
| verifyAttributes.keyUsage | ‘S0’ |
| verifyAttributes.algorithm | ‘R’ |
| verifyAttributes.modeOfUse | ‘V’ |
| verifyAttributes.cryptoMethod | rsassaPss |
| vendorAttributes |
KeyManagement.ImportKey Output Data
| Parameter Name | Example Value |
|---|---|
| verifyAttributes.keyUsage | ‘00’ |
| verifyAttributes.algorithm | ‘T’ |
| verifyAttributes.modeOfUse | ‘V’ |
| verifyAttributes.cryptoMethod | zero |
| verifyData | <key check value> |
| keyLength | 128 |
Importing a 16-byte DES key for pin encryption with a key check value in the input
For this example, the following input data is available:
Name of key to be imported = testKey
Name of the key used to decrypt the encrypted key value = masterKey
Encrypted key value =
KeyManagement.ImportKey Input Data
| Parameter Name | Example Value |
|---|---|
| key | testKey |
| keyAttributes.keyUsage | ‘P0’ (Similar to use but a more precise key usage) |
| keyAttributes.algorithm | ‘T’ |
| keyAttributes.modeOfUse | ‘E’ |
| keyAttributes.cryptoMethod | 0 |
| value | <encrypted key value> |
| decryptKey | masterKey |
| decryptMethod | ecb |
| verificationData | <key check value> |
| verifyKey | |
| verifyAttributes.keyUsage | ‘00’ |
| verifyAttributes.algorithm | ‘T’ |
| verifyAttributes.modeOfUse | ‘V’ |
| verifyAttributes.cryptoMethod | zero |
| vendorAttributes |
Likewise, the following output data is expected:
KeyManagement.ImportKey Output Data
| Parameter Name | Example Value |
|---|---|
| verifyAttributes | null |
| verifyData | |
| keyLength | 128 |
Importing a 16-byte DES key for macing (MAC Algorithm 3)
For this example, the following input data is available:
Name of key to be imported = testKey
Name of the key used to decrypt the encrypted key value = masterKey
Encrypted key value =
KeyManagement.ImportKey Input Data
| Parameter Name | Example Value |
|---|---|
| key | testKey |
| keyAttributes.keyUsage | ‘M3’ (Similar to fwUse but a more precise key usage) |
| keyAttributes.algorithm | ‘T’ |
| kyAttributes.modeOfUse | ‘G’ |
| keyAttributes.cryptoMethod | 0 |
| value | <encrypted key value> |
| decryptKey | masterKey |
| decryptMethod | ecb |
| verificationData | |
| verifyKey | |
| verifyAttributes | null |
| vendorAttributes |
KeyManagement.ImportKey Output Data
| Parameter Name | Example Value |
|---|---|
| verifyAttributes.keyUsage | ‘00’ |
| verifyAttributes.algorithm | ‘T’ |
| verifyAttributes.modeOfUse | ‘V’ |
| verifyAttributes.cryptoMethod | zero |
| verifyData | <key check value> |
| keyLength | 128 |
Importing a 2048-bit Host RSA public key
For this example, the following input data is available:
Name of key to be imported = HostKey
Name of the key used to verify the signature = sigIssuerVendor
Key value =
KeyManagement.ImportKey Input Data
| Parameter Name | Example Value |
|---|---|
| key | hostKey |
| value | <key value> |
| use | rsaPublicVerify |
| sigKey | sigIssuerVendor |
| rsaSignatureAlgorithm | rsassaPss |
| signature | <signature generated by the vendor signature issuer> |
For this example, the following output data is expected:
RSA Key Check Mode = sha256 digest
Key Check Value =
KeyManagement.ImportKey Output Data
| Parameter Name | Example Value |
|---|---|
| rsaKeyCheckMode | sha256 |
| keyCheckValue | <sha256 digest> |
KeyManagement.ImportKey Input Data
| Parameter Name | Example Value |
|---|---|
| key | hostKey |
| keyAttributes.keyUsage | ‘S0’ |
| keyAttributes.algorithm | ‘R’ |
| keyAttributes.modeOfUse | ‘V’ |
| keyAttributes.cryptoMethod | 0 |
| value | <key value> |
| decryptKey | |
| decryptMethod | 0 |
| verificationData | <signature generated by the vendor signature issuer> |
| verifyKey | sigIssuerVendor |
| verifyAttributes.KeyUsage | ‘S1’ |
| verifyAttributes.Algorithm | ‘R’ |
| verifyAttributes.ModeOfUse | ‘V’ |
| verifyAttributes.CryptoMethod | rsassaPss |
| vendorAttributes |
KeyManagement.ImportKey Output Data
| Parameter Name | Example Value |
|---|---|
| verifyAttributes.algorithm | ‘R’ |
| verifyAttributes.modeOfUse | ‘V’ |
| verifyAttributes.CryptoMethod | sha256 |
| verifyData | <sha256 digest> |
| keyLength | 2048 |
Importing a 24-byte DES symmetric data encryption key via TR-31 keyblock
For this example, the following input data is available:
Name of key to be imported = testKey
Name of the key block protection key = masterKey
Key block =
KeyManagement.ImportKey Input Data
| Parameter Name | Example Value |
|---|---|
| Key | testKey |
| EncKey | masterKey |
| KeyBlock | <key block> |
For this example, the following output data is expected:
Key Length = triple length (192 bits) DES key
ImportKey Output Data None
KeyManagement.ImportKey Input Data
| Parameter Name | Example Value |
|---|---|
| key | testKey |
| keyAttributes.keyUsage | ‘D0’ |
| keyAttributes.algorithm | ‘T’ |
| keyAttributes.modeOfUse | ‘E’ |
| keyAttributes.cryptoMethod | 0 |
| value | <key block> |
| decryptKey | masterKey |
| decryptMethod | 0 |
| verificationData | |
| verifyKey | |
| verifyAttributes | null |
| vendorAttributes |
KeyManagement.ImportKey Output Data
| Parameter Name | Example Value |
|---|---|
| verifyAttributes | null |
| verifyData | |
| keyLength | 192 |
7.2.21 - TR-31 Key Use
This section contains a mapping of key usages as defined for TR-31 to the use values defined in this document. The use values are those defined for the use input/output fields of a number of different KeyManagement commands.
Keys imported within an ANS TR-31 key block have a usage encoded into the key block header (represented by BlockHeader in the KeyDetail commands), This usage specified in the key block header may be more specific than the Use values defined in this document. For consistency, the following table defines the corresponding Use value for each TR-31 key usage:
| TR-31 Value | TR-31 Mode(s) of use | Definition | use |
|---|---|---|---|
| “B0” | “X” | BDK Base Derivation Key | keyDerKey |
| “B1” | “X” | DUKPT Initial Key (also known as IPEK) | keyDerKey** pinRemote function* crypt macing |
| “C0” | “C”, “G”, “V” | CVK Card Verification Key | NA |
| “D0” | “B”, “D”, “E” | Data Encryption using ecb, cbc, cfb, ofb, ccm or ctr | crypt |
| “E0” | “X” | EMV/chip Issuer Master Key: Client cryptograms | rsaPublicVerify |
| “E1” | “X” | EMV/chip Issuer Master Key: Secure Messaging for Confidentiality | rsaPublicVerify |
| “E2” | “X” | EMV/chip Issuer Master Key: Secure Messaging for Integrity | rsaPublicVerify |
| “E3” | “X” | EMV/chip Issuer Master Key: Data Authentication Code | rsaPublicVerify |
| “E4” | “X” | EMV/chip Issuer Master Key: Dynamic Numbers | rsaPublicVerify |
| “E5” | “X” | EMV/chip Issuer Master Key: Card Personalization | rsaPublicVerify |
| “E6” | “X” | EMV/chip Issuer Master Key: Other | rsaPublicVerify |
| “I0” | “N” | Initialization Vector (IV) | NA |
| “K0” | “B”, “D”, “E” | Key Encryption or wrapping | keyEncKey svEncKey |
| “K1” | “B”, “D”, “E” | TR-31 Key Block Protection Key | anstr31Master |
| “M0” | “C”, “G”, “V” | ISO 16609 MAC algorithm 1 (using TDEA) | macing |
| “M1” | “C”, “G”, “V” | ISO 9797-1 MAC Algorithm 1 | macing |
| “M2” | “C”, “G”, “V” | ISO 9797-1 MAC Algorithm 2 | macing |
| “M3” | “C”, “G”, “V” | ISO 9797-1 MAC Algorithm 3 | macing |
| “M4” | “C”, “G”, “V” | ISO 9797-1 MAC Algorithm 4 | macing |
| “M5” | “C”, “G”, “V” | ISO 9797-1 MAC Algorithm 5 | macing |
| “P0” | “B”, “D”, “E” | PIN Encryption | pinRemote function* |
| “V0” | “C”, “G”, “V” | PIN verification, KPV, other algorithm | pinLocal function* |
| “V1” | “C”, “G”, “V” | PIN verification, IBM 3624 | pinLocal function* |
| “V2” | “C”, “G”, “V” | PIN Verification, VISA PVV | pinLocal function* |
*Note that function is listed here for backward compatibility, but pinLocal/pinRemote is the more accurate single-use value.
** The Base Derivation Key is used to derive the IPEK. When a dukpt IPEK is loaded, derived future keys are stored and the IPEK deleted. Therefore, while the IPEK is no longer loaded, future keys directly related to it are. pinRemote and optionally function are included as the primary use of an IPEK future key is to create a variant for PIN encryption. If the optional variant data encryption and MAC keys are supported, crypt and macing must be included. To use the optional data or MAC keys in a crypt command, key must be the name of the IPEK and Algorithm must be cryptTriDesCbc cryptTriDesMac. If the optional data encryption key is being used, Mode must be modeEncCrypt. The optional variant response data encryption and MAC keys are not supported.
7.2.22 - RestrictedKeyEndKey Command Usage
This sample command flow sequence shows how encryption keys can be derived/not derived if the master key has a restricted use. NOTE: In this example the master encryption key is loaded using the secure key entry command instead of using RKL commands. The loading with RKL works in the same way. Secure key entry based restricted master encryption key loading with RestrictedKeyEncKey flag:
New master keys loaded with restrictedKeyEncKey flag, encrypted with themselves
Loading derived keys:
Usage sample for derived keys
Master key restriction disallows loading of derived keys with different usage:
7.3 - Command Messages
7.3.1 - KeyManagement.GetKeyDetail
This command returns extended detailed information about the keys in the encryption module, including des,dukpt,aes,rsa private and public keys. This command will also return information on all keys loaded during manufacture that can be used by clients. Details relating to the keys loaded using OPT (via the ZKA ProtIsoPs protocol) are retrieved using the ZKA hsmLdi protocol. These keys are not reported by this command.
Command Message
Completion Message
Event Messages
None7.3.2 - KeyManagement.Initialization
The encryption module must be initialized before any encryption function can be used. Every call to KeyManagement.Initialization destroys all client keys that have been loaded or imported; it does not affect those keys loaded during manufacturing.
Usually this command is called by an operator task and not by the client program. Public keys imported under the rsa Signature based remote key loading scheme when public key deletion authentication is required will not be affected. However, if this command is requested in authenticated mode, public keys that require authentication for deletion will be deleted. This includes public keys imported under either the rsa Signature based remote key loading scheme or the TR34 RSA Certificate based remote key loading scheme.
Initialization also involves loading 'initial' client keys and local vendor dependent keys. These can be supplied, for example, by an operator through a keyboard, a local configuration file, remote RSA key management or possibly by means of some secure hardware that can be attached to the device. The client 'initial' keys would normally get updated by the client during a KeyManagement.ImportKey command as soon as possible. Local vendor dependent static keys (e.g. storage, firmware and offset keys) would normally be transparent to the client and by definition cannot be dynamically changed.
Where initial keys are not available immediately when this command is issued (i.e. when operator intervention is required), the Service Provider returns accessDenied and the client must await the KeyManagement.InitializedEvent.
During initialization an optional encrypted ID key can be stored in the HW module. The ID key and the corresponding encryption key can be passed as parameters; if not, they are generated automatically by the encryption module. The encrypted ID is returned to the client and serves as authorization for the key import function. The Capabilities command indicates whether or not the device will support this feature.
This function also resets the hsm terminal data, except session key index and trace number.
This function resets all certificate data and authentication public/private keys back to their initial states at the time of production (except for those public keys imported under the rsa Signature based remote key loading scheme when public key deletion authentication is required). Key-pairs created with KeyManagement.GenerateRSAKeyPair are deleted. Any keys installed during production, which have been permanently replaced, will not be reset. Any Verification certificates that may have been loaded must be reloaded. The Certificate state will remain the same, but the KeyManagement.LoadCertificate or KeyManagement.ReplaceCertificate commands must be called again.
When multiple ZKA HSMs are present, this command deletes all keys loaded within all ZKA logical HSMs."
Command Message
Completion Message
Event Messages
None7.3.3 - KeyManagement.DeriveKey
The encryption key in the secure key buffer or passed by the client is loaded in the encryption module. The key can be passed in clear text mode or encrypted with an accompanying 'key encryption key'. A key can be loaded in multiple unencrypted parts by combining the construct or secureConstruct value with the final usage flags within the use field. If the construct flag is used then the client must provide the key data through the value parameter, If secureConstruct is used then the encryption key part in the secure key buffer previously populated with the Keyboard.SecureKeyEntry command is used and value is ignored. Key parts loaded with the secureConstruct flag can only be stored once as the encryption key in the secure key buffer is no longer available after this command has been executed. The construct and secureConstruct construction flags cannot be used in combination.
Command Message
Completion Message
Event Messages
None7.3.4 - KeyManagement.Reset
Sends a service reset to the Service Provider.
Command Message
Completion Message
Event Messages
None7.3.5 - KeyManagement.ImportKey
The encryption key passed by the client is loaded in the encryption module. For secret keys, the key must be passed encrypted with an accompanying "key encrypting key" or "key block protection key". For public keys, they key is not required to be encrypted but is required to have verification data in order to be loaded.
Command Message
Completion Message
Event Messages
None7.3.6 - KeyManagement.DeleteKey
This command can be used to delete a key without authentication. Where an authenticated delete is required, the KeyManagement.StartAuthenticate command should be used.
Command Message
Completion Message
Event Messages
None7.3.7 - KeyManagement.ExportRSAIssuerSignedItem
This command is used to export data elements from the device, which have been signed by an offline Signature Issuer. This command is used when the default keys and Signature Issuer signatures, installed during manufacture, are to be used for remote key loading.
This command allows the following data items are to be exported:
-
The Security Item which uniquely identifies the device. This value may be used to uniquely identify a device and therefore confer trust upon any key or data obtained from this device.
-
The rsa public key component of a public/private key pair that exists within the device. These public/private key pairs are installed during manufacture. Typically, an exported public key is used by the host to encipher the symmetric key.
Command Message
Completion Message
Event Messages
None7.3.8 - KeyManagement.GenerateRSAKeyPair
This command will generate a new rsa key pair. The public key generated as a result of this command can subsequently be obtained by calling KeyManagement.ExportRSAEPPSignedItem. The newly generated key pair can only be used for the use defined in the use flag. This flag defines the use of the private key; its public key can only be used for the inverse function.
Command Message
Completion Message
Event Messages
None7.3.9 - KeyManagement.ExportRSAEPPSignedItem
This command is used to export data elements from the device that have been signed by a private key within the epp. This command is used in place of the KeyManagement.ExportRSAIssuerSignedItem command, when a private key generated within the device is to be used to generate the signature for the data item. This command allows an client to define which of the following data items are to be exported.
-
The Security Item which uniquely identifies the device. This value may be used to uniquely identify a device and therefore confer trust upon any key or data obtained from this device.
-
The rsa public key component of a public/private key pair that exists within the device.
Command Message
Completion Message
Event Messages
None7.3.10 - KeyManagement.GetCertificate
This command is used to read out the encryptor's certificate, which has been signed by the trusted Certificate Authority and is sent to the host. This command only needs to be called once if no new Certificate Authority has taken over. The output of this command will specify in the pkcs #7 message the resulting Primary or Secondary certificate.
Command Message
Completion Message
Event Messages
None7.3.11 - KeyManagement.ReplaceCertificate
This command is used to replace the existing primary or secondary Certificate Authority certificate already loaded into the KeyManagement. This operation must be done by an Initial Certificate Authority or by a Sub-Certificate Authority. These operations will replace either the primary or secondary Certificate Authority public verification key inside of the KeyManagement. After this command is complete, the client should send the KeyManagement.LoadCertificate and KeyManagement.GetCertificate commands to ensure that the new HOST and the encryptor have all the information required to perform the remote key loading process.
Command Message
Completion Message
Event Messages
None7.3.12 - KeyManagement.StartKeyExchange
This command is used to start communication with the host, including transferring the host's Key Transport Key, replacing the Host certificate, and requesting initialization remotely. This output value is returned to the host and is used in the
to verify that the encryptor is talking to the proper host.
The KeyManagement.ImportKey command end the key exchange process.
Command Message
Completion Message
Event Messages
None7.3.13 - KeyManagement.GenerateKCV
This command returns the Key Check Value (kcv) for the specified key.
Command Message
Completion Message
Event Messages
None7.3.14 - KeyManagement.LoadCertificate
This command is used to load a host certificate to make remote key loading possible. This command can be used to load a host certificate when there is not already one present in the encryptor as well as replace the existing host certificate with a new host certificate. The type of certificate (Primary or Secondary) to be loaded will be embedded within the actual certificate structure.
Command Message
Completion Message
Event Messages
None7.3.15 - KeyManagement.StartAuthenticate
This command is used to retrieve the data that needs to be signed and hence provided to the Authenticate command in order to perform an authenticated action on the device. If this command returns data to be signed then the Authenticate command must be used to call the command referenced by startAuthenticate. Any attempt to call the referenced command without using the Authenticate command, if authentication is required, shall result in AuthRequired.
Command Message
Completion Message
Event Messages
None7.4 - Unsolicited Messages
7.4.1 - KeyManagement.InitializedEvent
This event specifies that, as a result of a Initialization command, the encryption module is now initialized and the master key (where required) and any other initial keys are loaded; ready to import other keys
7.4.2 - KeyManagement.IllegalKeyAccessEvent
This event specifies that an error occurred accessing an encryption key. Possible situations for generating this event are listed in the description of lErrorCode.
7.4.3 - KeyManagement.CertificateChangeEvent
This event indicates that the certificate module state has changed from Primary to Secondary.
8 - Crypto Interface
This chapter defines the Crypto interface functionality and messages.
8.2 - General Information
8.2.1 - DUKPT
| Definitions and Abbreviations | |
|---|---|
| DUKPT | Derived Unique Key Per Transaction |
| BDK | Base Derivation Key |
| IPEK | Initial PIN Encryption Key |
| KSN | Key Serial Number. |
| TRSM | Tamper Resistant Security Module. |
For additional information see reference 45.
2.1 Default Key Name
The dukpt IPEK key is given a fixed name so multi-vendor clients can be developed without the need for vendor specific configuration tools.
If dukpt is supported, this key must be included in the KeyDetail output.
| Item Name | Description |
|---|---|
| “dukptIpek” | This key represents the IPEK, the derived future keys stored during import of the IPEK and the variant per transaction keys (PIN and optionally data and MAC). |
8.3 - Command Messages
8.3.1 - Crypto.GenerateRandom
This command is used to generate a random number.
Command Message
Completion Message
Event Messages
None8.3.2 - Crypto.CryptoData
The input data is either encrypted or decrypted using the specified or selected encryption mode. The input data is padded to the necessary length mandated by the encryption algorithm using the padding parameter. This input data is padded to necessary length mandated by the signature algorithm using padding parameter. Clients can use an alternative padding method by pre-formatting the data passed and combining this with the standard padding method. The start value (or Initialization Vector) can be provided as input data to this command, or it can be imported via TR-31 prior to requesting this command and referenced by name. The start value and start value key are both optional parameters.
Command Message
Completion Message
Event Messages
8.3.3 - Crypto.GenerateAuthentication
The Authentication data is generated using the specified mode. The available modes are defined in the Crypto.Capabilities command. This command can be used for Message Authentication Code generation (i.e. macing). The input data is padded to the necessary length mandated by the encryption algorithm using the padding parameter. This command can be used for asymmetric signature generation. This input data is padded to necessary length mandated by the signature algorithm using padding parameter. Clients can use an alternative padding method by pre-formatting the data passed and combining this with the standard padding method. The start value (or Initialization Vector) can be provided as input data to this command, or it can be imported via TR-31 prior to requesting this command and referenced by name. The start value and start value key are both optional parameters.
Command Message
Completion Message
Event Messages
8.3.4 - Crypto.VerifyAuthentication
The authentication data is verified using the specified mode. The available modes are defined in the Crypto.Capabilities command. This command can be used for MAC and signature verification. The input data is padded to the necessary length mandated by the encryption algorithm using the padding parameter. This input data is padded to necessary length mandated by the signature algorithm using padding parameter. Clients can use an alternative padding method by pre-formatting the data passed and combining this with the standard padding method. The start value (or Initialization Vector) can be provided as input data to this command, or it can be imported via TR-31 prior to requesting this command and referenced by name. The start value and start value key are both optional parameters.
Command Message
Completion Message
Event Messages
8.4 - Event Messages
8.4.1 - Pinpad.DUKPTKSNEvent
This event sends the DUKPT KSN of the key used in the command. The receiving TRSM uses this to derive the key from the BDK.
9 - Keyboard Interface
This chapter defines the Keyboard interface functionality and messages.
9.1 - Summary
This section describes the general interface for the following functions:
-
Entering Personal Identification Numbers (PINs)
-
Clear text data handling
-
Function key handling
If the PIN pad device has local display capability, display handling should be handled using the Text Terminal Unit (TTU) interface. The adoption of this specification does not imply the adoption of a specific security standard.
-
Only numeric PIN pads are handled in this specification.
9.2 - General Information
9.2.1 - Encrypting Touch Screen (ETS)
An encrypting touch screen device is a touch screen securely attached to a cryptographic device. It can be used as an alternative to an encrypting pin pad (EPP). It supports key management, encryption and decryption.
It is assumed that the ETS is a combined device. It overlays a display monitor which is used to display lead-through for a transaction. It is assumed that the display monitor is part of the Windows desktop, and can be the Windows primary monitor or any other monitor on the desktop. E.g. the following diagram shows 2 monitors extended across the desktop, with monitor 1 being the primary monitor and the ETS being overlaid on monitor 2 whose origin is (-1680.0).
The touch screen can optionally be used as a “mouse” for client purposes, while PIN operations are not in progress or optionally when non-secure PIN commands are in progress.
The CEN interface supports two types of ETS
- Those which activate touch areas defined by the client.
- Those which activate a random variation of touch areas defined by the client.
The Service Provider, when reporting its capabilities, reports the absolute position of the ETS in Windows desktop coordinates. This allows the client to locate the ETS device in a multi-monitor system and relate it to a monitor on the desktop.
At any point in time, a single touch area of the ETS can operate in one of 4 modes:-
-
Mouse mode - a "touch" simulates a mouse click. This mode is optional. This may not be supported by some ETS devices. Configuration of the click is vendor specific. e.g. WM_LBUTTONDOWN. This is also the mode that, if supported, is active when none of the other modes are active.
-
Data mode - a "touch" maps to an key and the value of the key is returned in an event (as in clear numeric entry using Keyboard.DataEntry).
-
PIN mode - a "touch" maps to an key and the value of the key is returned in an event only if the key pressed is not Fk0 through Fk9 (as in PIN entry using Keyboard.PinEntry).
-
Secure mode - a "touch" maps to an key and the value of the key is returned in an event only if the key pressed is not Fk0 through Fk9 and not Fk_A through Fk_F (as in key entry using Keyboard.SecureKeyEntry).
The following concepts are introduced to define the relationship between the monitor and the ETS:-
-
Touch Key – an area of the monitor which reacts to touch in Data, PIN and Secure modes.
-
Touch Frame – an area of the monitor onto which Touch Keys can be placed. There can be one or more Touch Frames. There may be just one Touch Frame which covers the whole monitor. Areas within a Touch Frame, not defined as a Touch Key, do not react to touch. Generally in PIN and Secure modes, there would be only one Touch Frame covering the whole monitor. An empty Touch Frame disables that part of the monitor.
-
Mouse area – an area outside of all Touch Frames in which touches behave like a mouse.
-
Thus Data, PIN and Secure modes operate in a single Touch Frame or multiple Touch Frames. Mouse mode operates outside a Touch Frame, and is optional.
Note that there is a perceived risk in separating the drawing functionality from the touch functionality, but this type of risk is present in today’s keyboard based systems. e.g. a client can draw on a monitor to prompt the user to enter a PIN and then enables the EPP for clear data entry. So the risk is no different than with an EPP – the client has to be trusted.
Depending upon the type of device, the client must then either inform the Service Provider as to the active key positions in the form of Touch Frames and Touch Keys using the Keyboard.DefineLayout command, or obtain them from the Service Provider using the Keyboard.GetLayout command. This collection is now referred to as a "Touch Keyboard definition".
The client then uses the normal PIN commands to enable the touch keyboard definition on the ETS device:
- PIN entry Keyboard.PinEntry
- Clear data entry Keyboard.DataEntry
- Secure key entry Keyboard.SecureKeyEntry
These commands are referred to as "keyboard entry commands" throughout the remainder of this document.
PCI compliance means that Keyboard.PinEntry and Keyboard.SecureKeyEntry can only be used with a single Touch Frame that covers the entire monitor. i.e. Mouse mode cannot be mixed with either PIN or Secure mode. If a Touch Key (or areas) is defined for an key value and that key value is not subsequently specified as active in a Keyboard.PinEntry, Keyboard.DataEntry or Keyboard.SecureKeyEntry command, then the Touch Key is made inactive.
Layouts defined with the Keyboard.DefineLayout command are persistent.
Example 1 – this screen only uses Data mode – the entire screen is a Touch Frame. Mouse mode is not used.
Example 2 – this shows a monitor with two Touch Frames and 14 Touch Keys. The space within the Touch Frames not defined by a Touch Key are inactive (do not respond to touch). All areas outside a Touch Frame operate in Mouse mode. This example shows two Mouse mode "keys". e.g. Windows "Button", HTML "BUTTON" or a custom control. Other touches in Mouse mode are normally dealt with by the client event engine. However, this can be restricted – see example 3.
Example 3 - this screen uses Mouse and Data modes – Mouse mode is used only in a restricted area. The touch keyboard definition has 3 frames. Frame 1 has no Touch Keys. Frame 2 has 2 Touch Keys; Frame 3 has 12 Touch Keys.
9.2.2 - Secure Key Entry
This section provides additional information to describe how encryption keys are entered securely through the PIN pad keyboard and also provides examples of possible keyboard layouts.
Keyboard Layout
The following sections describe what is returned within the GetSecureKeyDetail output parameters to describe the physical keyboard layout. These descriptions are purely examples to help understand the usage of the parameters they do not indicate a specific layout per Key Entry Mode.
In the following section all references to parameters relate to the output fields of the GetSecureKeyDetail command.
When keyEntryMode represents a regular shaped PIN pad (regUnique or regShift) then hexKeys must contain one entry for each physical key on the PIN pad (i.e. the product of Rows by Columns). On a regular shaped PIN pad the client can choose to ignore the position and size data and just use the rows and columns parameters to define the layout. However, a Service Provider must return the position and size data for each key.
keyEntryMode == regUnique
When keyEntryMode is regUnique then the values in the array report which physical keys are associated with the function keys 0-9, A-F and any other function keys that can be enabled as defined in the funcKeyDetail parameter. Any positions on the PIN pad that are not used must be defined as a fkUnused in the fk and shiftFk field of the hexKeys structure.
1 2 3 Clear (A)
4 5 6 Cancel (B)
7 8 9 Enter (C)
(D) 0 (E) (F)
In the above example, where all keys are the same size and the hex digits are located as shown the hexKeys will contain the entries in the array as defined in the following table.
| Index | xPos | yPos | xSize | ySize | fk | shiftfk |
|---|---|---|---|---|---|---|
| 0 | 0 | 0 | 250 | 250 | fk1 | fkUnused |
| 1 | 250 | 0 | 250 | 250 | fk2 | fkUnused |
| 2 | 500 | 0 | 250 | 250 | fk3 | fkUnused |
| 3 | 750 | 0 | 250 | 250 | fkA | fkUnused |
| 4 | 0 | 250 | 250 | 250 | fk4 | fkUnused |
| 5 | 250 | 250 | 250 | 250 | fk5 | fkUnused |
| 6 | 500 | 250 | 250 | 250 | fk6 | fkUnused |
| 7 | 750 | 250 | 250 | 250 | fkB | fkUnused |
| 8 | 0 | 500 | 250 | 250 | fk7 | fkUnused |
| 9 | 250 | 500 | 250 | 250 | fk8 | fkUnused |
| 10 | 500 | 500 | 250 | 250 | fk9 | fkUnused |
| 11 | 750 | 500 | 250 | 250 | fkC | fkUnused |
| 12 | 0 | 750 | 250 | 250 | fkD | fkUnused |
| 13 | 250 | 750 | 250 | 250 | fk0 | fkUnused |
| 14 | 500 | 750 | 250 | 250 | fkE | fkUnused |
| 15 | 750 | 750 | 250 | 250 | fkF | fkUnused |
keyEntryMode == regShift
When keyEntryMode is regShift then the values in the array report which physical keys are associated with the function keys 0-9, A-F, and the shift key as defined in the funcKeyDetail parameter. Other function keys as defined by the funcKeyDetail parameter that can be enabled must also be reported. Any positions on the PIN pad that are not used must be defined as a fkUnused in the fk and shiftFk field of the hexKeys structure. Digits 0 to 9 are accessed through the numeric keys as usual. Digits A to F are accessed by using the shift key in combination with another function key, e.g. shift-0 (zero) is hex digit A.
1 (B) 2 (C) 3 (D) Clear
4 (E) 5 (F) 6 Cancel
7 8 9 Enter
SHIFT 0 (A)
In the above example, where all keys are the same size and the hex digits 'A' to 'F' are accessed through shift '0' to '5', then the hexKeys will contain the entries in the array as defined in the following table.
| Index | xPos | yPos | xSize | ySize | fk | shiftfk |
|---|---|---|---|---|---|---|
| 0 | 0 | 0 | 250 | 250 | fk1 | fkB |
| 1 | 250 | 0 | 250 | 250 | fk2 | fkC |
| 2 | 500 | 0 | 250 | 250 | fk3 | fkD |
| 3 | 750 | 0 | 250 | 250 | fkClear | fkUnused |
| 4 | 0 | 250 | 250 | 250 | fk4 | fkE |
| 5 | 250 | 250 | 250 | 250 | fk5 | fkF |
| 6 | 500 | 250 | 250 | 250 | fk6 | fkUnused |
| 7 | 750 | 250 | 250 | 250 | fkCancel | fkUnused |
| 8 | 0 | 500 | 250 | 250 | fk7 | fkUnused |
| 9 | 250 | 500 | 250 | 250 | fk8 | fkUnused |
| 10 | 500 | 500 | 250 | 250 | fk9 | fkUnused |
| 11 | 750 | 500 | 250 | 250 | fkEnter | fkUnused |
| 12 | 0 | 750 | 250 | 250 | fkShift | fkUnused |
| 13 | 250 | 750 | 250 | 250 | fk0 | fkA |
| 14 | 500 | 750 | 250 | 250 | fkUnused | fkUnused |
| 15 | 750 | 750 | 250 | 250 | fkUnused | fkUnused |
keyEntryMode == irregShift
When keyEntryMode represents an irregular shaped PIN pad the rows and columns parameters define the ratio of the width to height, i.e. square if the parameters are the same or rectangular if Columns is larger than rows, etc. A Service Provider must return the position and size data for each key reported.
When keyEntryMode is irregShift then the values in the array must be the function keys codes for 0-9 and the shift key as defined in the funcKeyDetail parameter. Other function keys as defined by the funcKeyDetail parameter that can be enabled must also be reported. Any positions on the PIN pad that are not used must be defined as a fkUnused in the fk and shiftfk field of the hexKeys structure. Digits 0 to 9 are accessed through the numeric keys as usual. Digits A - F are accessed by using the shift key in combination with another function key, e.g. shift-0(zero) is hex digit A.
1 (B) 2 (C) 3 (D) Clear
4 (E) 5 (F) 6 Cancel
7 8 9 Enter
0 (A)
SHIFT
In the above example, where the hex digits 'A' to 'F' are accessed through shift '0' to ‘5’, columns will be 4, rows will be 5 and the hexKeys will contain the entries in the array as defined in the following table.
| Index | xPos | yPos | xSize | ySize | fk | shiftfk |
|---|---|---|---|---|---|---|
| 0 | 0 | 0 | 250 | 200 | fk1 | fkB |
| 1 | 250 | 0 | 250 | 200 | fk2 | fkC |
| 2 | 500 | 0 | 250 | 200 | fk3 | fkD |
| 3 | 750 | 0 | 250 | 200 | fkClear | fkUnused |
| 4 | 0 | 200 | 250 | 200 | fk4 | fkE |
| 5 | 250 | 200 | 250 | 200 | fk5 | fkF |
| 6 | 500 | 200 | 250 | 200 | fk6 | fkUnused |
| 7 | 750 | 200 | 250 | 200 | fkCancel | fkUnused |
| 8 | 0 | 400 | 250 | 200 | fk7 | fkUnused |
| 9 | 250 | 400 | 250 | 200 | fk8 | fkUnused |
| 10 | 500 | 400 | 250 | 200 | fk9 | fkUnused |
| 11 | 750 | 400 | 250 | 200 | fkEnter | fkUnused |
| 12 | 0 | 600 | 250 | 200 | fkUnused | fkUnused |
| 13 | 250 | 600 | 250 | 200 | fk0 | fkA |
| 14 | 500 | 600 | 250 | 200 | fkUnused | fkUnused |
| 15 | 750 | 600 | 250 | 200 | fkUnused | fkUnused |
| 16 | 0 | 800 | 1000 | 200 | fkShift | fkUnused |
keyEntryMode == irregUnique
When keyEntryMode is irregUnique then the values in the array report which physical keys are associated with the function keys 0-9, A-F and any other function keys that can be enabled as defined in the FuncKeyDetail parameter. The rows and columns parameters define the ratio of the width to height, i.e. square if the parameters are the same or rectangular if columns is larger than rows, etc. A Service Provider must return the position and size data for each key.
In the above example, where an alphanumeric keyboard supports secure key entry and the hex digits are located as shown, the hexKeys will contain the entries in the array as defined in the following table. All the hex digits and function keys that can be enabled must be included in the array; in addition any keys that would help a client display an image of the keyboard can be included. In this example only the PIN pad digits (the keys on the right) and the unique hex digits are reported. Note that the position data in this example may not be 100% accurate as the diagram is not to scale.
| Index | xPos | yPos | xSize | ySize | fk | shiftfk |
|---|---|---|---|---|---|---|
| 0 | 780 | 18 | 40 | 180 | fk1 | fkUnused |
| 1 | 830 | 18 | 40 | 180 | fk2 | fkUnused |
| 2 | 880 | 18 | 40 | 180 | fk3 | fkUnused |
| 3 | 930 | 18 | 60 | 180 | fkCancel | fkUnused |
| 4 | 780 | 216 | 40 | 180 | fk4 | fkUnused |
| 5 | 830 | 216 | 40 | 180 | fk5 | fkUnused |
| 6 | 880 | 216 | 40 | 180 | fk6 | fkUnused |
| 7 | 930 | 216 | 60 | 180 | fkEnter | fkUnused |
| 8 | 780 | 414 | 40 | 180 | fk7 | fkUnused |
| 9 | 830 | 414 | 40 | 180 | fk8 | fkUnused |
| 10 | 880 | 414 | 40 | 180 | fk9 | fkUnused |
| 11 | 930 | 414 | 60 | 180 | fkClear | fkUnused |
| 12 | 780 | 612 | 40 | 180 | fkUnused | fkUnused |
| 13 | 830 | 612 | 40 | 180 | fk0 | fkUnused |
| 14 | 880 | 612 | 40 | 180 | fkUnused | fkUnused |
| 15 | 930 | 612 | 60 | 180 | fkUnused | fkUnused |
| 16 | 680 | 810 | 40 | 180 | fkA | fkUnused |
| 17 | 730 | 810 | 40 | 180 | fkB | fkUnused |
| 18 | 780 | 810 | 40 | 180 | fkC | fkUnused |
| 19 | 830 | 810 | 40 | 180 | fkD | fkUnused |
| 20 | 880 | 810 | 40 | 180 | fkE | fkUnused |
| 21 | 930 | 810 | 60 | 180 | fkF | fkUnused |
9.2.3 - Command Usage
This section provides an example of the sequence of commands required to enter an encryption key securely. In the following sequence, the client retrieves the keyboard secure key entry mode and associated keyboard layout and displays an image of the keyboard for the user. It then gets the first key part, verifies the KCV for the key part and stores it. The sequence is repeated for the second key part and then finally the key part is activated.
9.3 - Command Messages
9.3.1 - Keyboard.GetFuncKeyDetail
This command returns information about the names of the Function Keys supported by the device. Location information is also returned for the supported FDKs (Function Descriptor Keys). This includes screen overlay FDKs.
This command should be issued before the first call to Keyboard.PinEntry or Keyboard.DataEntry to determine which Function Keys (FKs) and Function Descriptor Keys (FDKs) are available and where the FDKs are located. Then, in these two commands, they can then be specified as Active and Terminate keys and options on the customer screen can be aligned with the active FDKs.
Command Message
Completion Message
Event Messages
None9.3.2 - Keyboard.GetLayout
This command allows a client to retrieve layout information for any device. Either one layout or all defined layouts can be retrieved with a single request of this command.
There can be a layout for each of the different types of keyboard entry modes, if the vendor and the hardware support these different methods. The types of keyboard entry modes are: (1) Data Entry mode which corresponds to the Keyboard.DataEntry command, (2) PIN Entry mode which corresponds to the Keyboard.PinEntry command, (3) Secure Key Entry mode which corresponds to the Keyboard.SecureKeyEntry command. The layouts can be preloaded into the device, if the device supports this, or a single layout can be loaded into the device immediately prior to the keyboard command being requested.
Command Message
Completion Message
Event Messages
None9.3.3 - Keyboard.PinEntry
This function stores the pin entry via the pin pad device. From the point this function is invoked, pin digit entries are not passed to the client. For each pin digit, or any other active key entered, an execute notification event Keyboard.KeyEvent is sent in order to allow a client to perform the appropriate display action (i.e. when the pin pad has no integrated display). The client is not informed of the value entered. The execute notification only informs that a key has been depressed.
The Keyboard.EnterDataEvent will be generated when the PIN pad is ready for the user to start entering data.
Some PIN pad devices do not inform the client as each PIN digit is entered, but locally process the PIN entry based upon minimum pin length and maximum PIN length input parameters.
When the maximum number of pin digits is entered and the flag autoEnd is true, or a terminating key is pressed after
the minimum number of pin digits is entered, the command completes.If the
Terminating FDKs can have the functionality of
If maxLen is zero, the Service Provider does not terminate the command unless the client sets terminateKeys or terminateFDKs. In the event that terminateKeys or terminateFDKs are not set and maxLen is zero, the command will not terminate and the client must issue a Cancel command.
If active the fkCancel and fkClear keys will cause the PIN buffer to be cleared. The fkBackspace key will cause the last key in the PIN buffer to be removed.
Terminating keys have to be active keys to operate.
If this command is cancelled by a CancelAsyncRequest the PIN buffer is not cleared.
If maxLen has been met and autoEnd is set to False, then all numeric keys will automatically be disabled. If the clear or backspace key is pressed to reduce the number of entered keys, the numeric keys will be re-enabled.
If the enter key (or FDK representing the enter key - note that the association of an FDK to enter functionality is vendor specific) is pressed prior to minLen being met, then the enter key or FDK is ignored. In some cases the PIN pad device cannot ignore the enter key then the command will complete normally. To handle these types of devices the client should use the output parameter digits field to check that sufficient digits have been entered. The client should then get the user to re-enter their PIN with the correct number of digits.
If the client makes a call to Pinpad.GetPinblock or a local verification command without the minimum PIN digits having been entered, either the command will fail or the PIN verification will fail.
It is the responsibility of the client to identify the mapping between the FDK code and the physical location of the FDK.
Command Message
Completion Message
Event Messages
9.3.4 - Keyboard.DataEntry
This function enables keyboard insercure mode and report entered key in clear text with solicited events. For PIN pad device, this command will clear the pin unless the client has requested that the pin be maintained through the Pinpad.MaintainPin command.
Command Message
Completion Message
Event Messages
9.3.5 - Keyboard.Reset
Sends a service reset to the Service Provider.
Command Message
Completion Message
Event Messages
None9.3.6 - Keyboard.SecureKeyEntry
This command allows a full length symmetric encryption key part to be entered directly into the device without being exposed outside of the device. From the point this function is invoked, encryption key digits (fk0 to fk9 and fkA to fkF) are not passed to the client. For each encryption key digit, or any other active key entered (except for shift), an execute notification event Keyboard.KeyEvent is sent in order to allow a client to perform the appropriate display action (i.e. when the device has no integrated display). When an encryption key digit is entered the client is not informed of the value entered, instead zero is returned.
The Keyboard.EnterDataEvent will be generated when the device is ready for the user to start entering data.
The keys that can be enabled by this command are defined by the FuncKeyDetail parameter of the Keyboard.SecureKeyEntry command. Function keys which are not associated with an encryption key digit may be enabled but will not contribute to the secure entry buffer (unless they are Cancel, Clear or Backspace) and will not count towards the length of the key entry. The Cancel and Clear keys will cause the encryption key buffer to be cleared. The Backspace key will cause the last encryption key digit in the encryption key buffer to be removed.
If autoEnd is TRUE the command will automatically complete when the required number of encryption key digits have been added to the buffer.
If autoEnd is FALSE then the command will not automatically complete and Enter, Cancel or any terminating key must be pressed. When keyLen hex encryption key digits have been entered then all encryption key digits keys are disabled. If the Clear or Backspace key is pressed to reduce the number of entered encryption key digits below usKeyLen, the same keys will be reenabled.
Terminating keys have to be active keys to operate.
If an FDK is associated with Enter, Cancel, Clear or Backspace then the FDK must be activated to operate. The Enter and Cancel FDKs must also be marked as a terminator if they are to terminate entry. These FDKs are reported as normal FDKs within the KeyEvent, clients must be aware of those FDKs associated with Cancel, Clear, Backspace and Enter and handle any user interaction as required. For example, if the fdk01 is associated with Clear, then the client must include the fk_fdk01 FDK code in the activeFDKs parameter (if the clear functionality is required). In addition when this FDK is pressed the Keyboard.KeyEvent will contain the fk_fdk01 mask value in the digit field. The client must update the user interface to reflect the effect of the clear on the encryption key digits entered so far.
On some devices that are configured as either regularUnique or irregularUnique all the function keys on the device will be associated with hex digits and there may be no FDKs available either. On these devices there may be no way to correct mistakes or cancel the key encryption entry before all the encryption key digits are entered, so the client must set the autoEnd flag to TRUE and wait for the command to auto-complete. Clients should check the KCV to avoid storing an incorrect key component.
Encryption key parts entered with this command are stored through either the KeyManagement.ImportKey. Each key part can only be stored once after which the secure key buffer will be cleared automatically.
Command Message
Completion Message
Event Messages
9.3.7 - Keyboard.KeypressBeep
This command is used to enable or disable the device from emitting a beep tone on subsequent key presses of active or in-active keys. This command is valid only on devices which have the capability to support client control of automatic beeping. See Keyboard.Capabilities structure for information.
Command Message
Completion Message
Event Messages
None9.3.8 - Keyboard.DefineLayout
This command allows a client to configure a layout for any device. One or more layouts can be defined with a single request of this command.
There can be a layout for each of the different types of keyboard entry modes, if the vendor and the hardware supports these different methods. The types of keyboard entry modes are (1) Mouse mode,(2) Data mode which corresponds to the Keyboard.DataEntry command, (3) PIN mode which corresponds to the Keyboard.PinEntry command,(4) Secure mode which corresponds to the Keyboard.SecureKeyEntry command. One or more layouts can be preloaded into the device, if the device supports this, or a single layout can be loaded into the device immediately prior to the keyboard command being requested.
If a Keyboard.DataEntry, Keyboard.PinEntry, or Keyboard.SecureKeyEntry command is already in progress (or queued), then this command is rejected with a command result of SequenceError.
Layouts defined with this command are persistent.
Command Message
Completion Message
Event Messages
None9.4 - Event Messages
9.4.1 - Keyboard.KeyEvent
This event specifies that any active key has been pressed at the PIN pad. It is used if the device has no internal display unit and the client has to manage the display of the entered digits. It is the responsibility of the client to identify the mapping between the FDK code and the physical location of the FDK.
9.4.2 - Keyboard.EnterDataEvent
This mandatory event notifies the client when the device is ready for the user to start entering data.
9.4.3 - Keyboard.LayoutEvent
This event sends the layout for a specific keyboard entry mode if the layout has changed since it was loaded (i.e. if a float action is being used).
10 - Pinpad Interface
This chapter defines the Pinpad interface functionality and messages.
10.1 - Summary
This section describes the general interface for the following functions:
- Administration of encryption devices
- PIN verification
- PIN block generation (encrypted PIN)
- PIN presentation to chipcard
- EMV 4.0 PIN blocks, EMV 4.0 public key loading, static and dynamic data verification
10.2 - General Information
10.2.1 - DUKPT
| Definitions and Abbreviations | |
|---|---|
| DUKPT | Derived Unique Key Per Transaction |
| BDK | Base Derivation Key |
| IPEK | Initial PIN Encryption Key |
| KSN | Key Serial Number. |
| TRSM | Tamper Resistant Security Module. |
2.1 Default Key Name
The dukpt IPEK key is given a fixed name so multi-vendor clients can be developed without the need for vendor specific configuration tools.
If dukpt is supported, this key must be included in the KeyDetail output.
| Item Name | Description |
|---|---|
| “dukptIpek” | This key represents the IPEK, the derived future keys stored during import of the IPEK and the variant per transaction keys (PIN and optionally data and MAC). |
10.3 - Command Messages
10.3.1 - Pinpad.GetQueryPCIPTSDeviceId
This command is used to report information in order to verify the PCI Security Standards Council PIN transaction security (PTS) certification held by the PIN device. The command provides detailed information in order to verify the certification level of the device. Support of this command by the Service Provider does not imply in anyway the certification level achieved by the device.
Command Message
Completion Message
Event Messages
None10.3.2 - Pinpad.LocalDES
The PIN, which was entered with the GetPin command, is combined with the requisite data specified by the DES validation algorithm and locally verified for correctness. The result of the verification is returned to the client. This command will clear the PIN unless the client has requested that the PIN be maintained through the Pinpad.MaintinPin command.
Command Message
Completion Message
Event Messages
None10.3.3 - Pinpad.LocalVisa
The PIN, which was entered with the GetPin command, is combined with the requisite data specified by the VISA validation
algorithm and locally verified for correctness. The result of the verification is returned to the client.
This command will clear the PIN unless the client has requested that the PIN be maintained through the
Pinpad.MaintinPin command.
Command Message
Completion Message
Event Messages
None10.3.4 - Pinpad.PresentIDC
The PIN, which was entered with the GetPin command, is combined with the requisite data specified by the IDC presentation algorithm and presented to the smartcard contained in the ID card unit. The result of the presentation is returned to the client. This command will clear the PIN unless the client has requested that the PIN be maintained through the Pinpad.MaintinPin command.
Command Message
Completion Message
Event Messages
None10.3.5 - Pinpad.Reset
Sends a service reset to the Service Provider.
Command Message
Completion Message
Event Messages
None10.3.6 - Pinpad.MaintainPin
This command is used to control if the PIN is maintained after a PIN processing command for subsequent use by other PIN processing commands. This command is also used to clear the PIN buffer when the PIN is no longer required.
Command Message
Completion Message
Event Messages
None10.3.7 - Pinpad.SetPinBlockData
This function should be used for devices which need to know the data for the PIN block before the PIN is entered by the user. Keyboard.GetPin and Pinpad.GetPinBlock should be called after this command. For all other devices Unsupported will be returned here. If this command is required and it is not called, the Keyboard.GetPin command will fail with the generic error SequenceError. If the input parameters passed to this commad and Pinpad.GetPinBlock are not identical, the Pinpad.GetPinBlock command will fail with the generic error InvalidData. The data associated with this command will be cleared on a Pinpad.GetPinBlock command.
Command Message
Completion Message
Event Messages
None10.3.8 - Pinpad.GetPinBlock
This function takes the account information and a PIN entered by the user to build a formatted PIN. Encrypting this formatted PIN once or twice returns a PIN block which can be written on a magnetic card or sent to a host. The PIN block can be calculated using one of the algorithms specified in the Pinpad.Capabilities command. This command will clear the PIN unless the client has requested that the PIN be maintained through the Pinpad.MaintinPin command.
Command Message
Completion Message
Event Messages
10.4 - Event Messages
10.4.1 - Pinpad.DUKPTKSNEvent
This event sends the DUKPT KSN of the key used in the command. The receiving TRSM uses this to derive the key from the BDK.
11 - Printer Interface
This chapter defines the Printer interface functionality and messages.
11.1 - Summary
This specification describes the functionality of the services provided by banking printers and scanning devices under XFS, focusing on the following areas:
- client programming for printing
- print document definition
- scanning images for devices such as check scanners
The XFS printer interface is implemented around a forms model which also standardizes the basic document definition.
11.2 - General Information
11.2.1 - Banking Printer Types
The XFS printer service defines and supports five types of banking printers through a common interface:
-
Receipt Printer
The receipt printer is used to print cut sheet documents. It may or may not require insert or eject operations, and often includes an operator identification device, e.g. Teller A and Teller B lights, for shared operation. -
Journal Printer
The journal is a continuous form device used to record a hardcopy audit trail of transactions, and for certain report printing requirements. -
Passbook Printer
The passbook device is physically and functionally the most complex printer. The XFS definition supports automatic positioning of the book, as well as read/write capability for an optional integrated magnetic stripe. The implementation also manages the book geometry - i.e. the margins and centerfolds - presenting the simplest possible client interface while delivering the full range of functionality.Some passbook devices also support the dispensing of new passbooks from up to four passbook paper sources (upper, aux, aux2, lower). Some passbook devices may also be able to place a full passbook in a parking station, print the new passbook and return both to the customer. Passbooks can only be dispensed or moved from the parking station if there is no other media in the print position or in the entry/exit slot.
-
Document Printer
Document printing is similar to receipt printing - a set of fields are positioned on one or more inserted sheets of paper - but the focus is on full-size forms. It should be noted that the XFS environment supports the printing of text and graphic fields from the client. The electronic printing of the form image (the template portion of the form which is usually pre-printed with dot-matrix style printers) may also be printed by the client. -
Scanner Printer
The scanner printer is a device incorporating both the capabilities to scan inserted documents and optionally to print on them. These devices may have more than one area where documents may be retained.
Additional hardware components, like scanners, stripe readers, OCR readers, and stamps, normally attached directly to the printer are also controlled through this interface. Additionally, the Printer and Scanning class interface can also be used for devices that are capable of scanning without necessarily printing. This includes devices such as Check Scanners.
The specification refers to the terms paper and media. When the term paper is used this refers to paper that is situated in a paper supply attached to the device. The term media is used for media that is inserted by the customer (e.g. check and other material that is scanned) or that is issued to the customer (e.g. a receipt or statement). Receipt, document and passbook printers with white passbook dispensing capability have both. As soon as the paper gets printed it becomes media. Scanners only have media. The term media does not apply to journal printers. When paper is in the print position it is classified as media, on some printers that maintain paper under the print head there will always be both media and paper.
11.2.2 - Forms Model
The XFS printing class functionality is based on a “forms” model for printing. Banking documents are represented as a series of text and/or graphic fields output from the client and positioned on the document by the XFS printing system.
The form is an object which includes the positioning and presentation information for each of the fields in the document. The client selects a form and supplies only the field data and the control parameters to fully define the print document.
The form objects are owned and managed by the XFS printing service. To optimize maintainability of the system, the client can query the service for the list of fields required to print a given form. Through this mechanism, it is not necessary to duplicate the field contents of forms in client authoring data. The figure below outlines the printing process from the client's view.
The XFS implementation recognizes that the form object must be supported by job-specific data to fully address printing requirements. As an example, a form defining a passbook print line will need to have its origin defined externally in order to be reused for different passbook lines. These job specific parameters are supplied on the Printer.PrintForm command.
In some cases, the client wants to print a block of data without considering it as a series of separate fields. One example is a line of journal data, fully formatted by the client. This can be handled by defining a one field form, or by use of the Printer.RawData command.
The document definition under XFS printing is standardized to provide portability across vendor implementations. The standard has been defined at the source language level for the document definition, allowing vendor differences at the runtime level to manage implementation specific dependencies, providing several areas where vendors can provide value-added extensions. As an example, a vendor providing a graphical form definition tool can produce the field definition object format directly. The XFS requirements for portability are:
- A vendor must be able to export print format in the standardized field definition source format for portability to other systems.
- A vendor must be able to import document formats produced on other systems in the standardized field definition source format.
- A vendor can extend the field definition source language, but any verbs included in the standard must be implemented strictly as defined by the standard. Import and export facilities must be tolerant of source language extensions, reporting but ignoring the exceptions.
11.2.3 - Command Overview
The basic operation of the print devices is managed using the two primary commands:
- Printer.GetQueryForm
This command retrieves the form header information, and the list of fields. - Printer.PrintForm
This command includes as parameter data the name of the form to select and the required field data values.
This approach combines in the most efficient manner the four logical steps required to print a form:
- Selecting a document form object.
- Querying the service for the list of fields.
- Supplying the data for each field.
- Issuing the print command.
By using Printer.GetQueryForm command to retrieve the list of field names, it is possible for a client to assemble the required set of fields for a form before locking the service. This minimizes the time that each client request ties up the service. Using Printer.GetQueryForm, it is also possible to query the attributes of a field. This command is generally not required for most clients.
The combination of form selection, field value presentation and the print action make it possible to express a complete print operation with Printer.PrintForm command. Where these multiple print functions represent a series of passbook lines (using the INDEX capability in the field definition), the Printer.PrintForm command provides support for management of the print line number. Note that if a form contains a tabular field (i.e. one with a non-zero INDEX value), and data is not supplied for some of the lines in the “table”, then those lines are left blank.
For printers with the capability to read from a passbook (OCR, MICR and/or magnetic stripe), the data is read with the Printer.ReadForm command. The data is written using the Printer.PrintForm command. Since these devices are usable only for passbook operations, they are not defined as separate logical devices.
Finally, the Printer.PrintRawFile command can be used to print a file that contains a complete print job in the native printer language. This file will have been created using the native Operating System API (e.g. Windows GDI).
11.2.4 - Form, Sub-Form, Field, Frame, Table and Media Definitions
This section outlines the format of the definitions of forms, the fields within them, optional tables and fields within the form, and the media on which they are printed.
11.2.4.1 - Definition Syntax
The syntactic rules for form, field and media definitions are as follows:
- White space
space, tab - Line continuation
backslash (\) - Line termination
CR, LF, CR/LF; line termination ends a "keyword section" (a keyword and its value[s]) - Keywords
must be all upper case - Names
(field/media/font names) any case; case is preserved;
Service Providers are case sensitive
- Strings
all strings must be enclosed in double quote characters (");
standard C escape sequences are allowed. - Comments
start with two forward slashes (//), end at line termination
Other Notes:
- The values of a keyword are separated by commas.
- If a keyword is present, all its values must be specified; default values are used only if the keyword is absent.
- Values that are character strings are marked with * in the definitions below and must be quoted as specified above.
- The order of attributes within the forms is not mandatory and the attributes may be defined in any order.
- All forms can be represented using either ISO 646 (ANSI) or UNICODE character encoding. If the UNICODE representation is used, then all Names and Strings are restricted to an internal representation of ISO 646 (ANSI) characters. Only the INITIALVALUE and FORMAT keyword values can have double byte values outside of the ISO 646 (ANSI) character set.
- If forms character encoding is UNICODE then, consistent with the UNICODE standard, the file prefix must be in Little Endian (0xFFFE) or Big Endian (0xFEFF) notation, such that UNICODE encoding is recognized.
- A form and its optional subforms that have multiple XFSFIELDs with the same fieldname are invalid. The formInvalid error will be returned if specified in the input to the command.
- A form that has multiple XFSSUBFORMs with the same subformname is invalid. The formInvalid error will be returned if specified in the input to the command.
- A form and its optional subforms that have multiple XFSFRAMEs with the same framename are invalid. The formInvalid error will be returned if specified in the input to the command.
11.2.4.2 - Form and Media Measurements
The UNIT keyword sections of the form and media definitions specify the base horizontal and vertical resolution as follows:
- The base value specifies the base unit of measurement.
- The x and y values specify the horizontal and vertical resolution as fractions of the base value (e.g. an x value of 10 and a base value of MM means that the base horizontal resolution is 0.1 mm).
The base resolutions thus defined by the UNIT keyword section of the XFSFORM definition are used as the units of the form definition keyword sections:
- SIZE (width and height values)
- ALIGNMENT (xoffset and yoffset values)
and of the sub-form definition keyword sections:
- POSITION (x and y values)
- SIZE (width and height values)
and of the field definition keyword sections:
- POSITION (x and y values)
- SIZE (width and height values)
- INDEX (xoffset and yoffset values)
and of the frame definition keyword sections:
- POSITION (x and y values)
- SIZE (width and height values)
- REPEATONX (xoffset value)
- REPEATONY (yoffset value)
The base resolutions thus defined by the UNIT keyword section of the XFSMEDIA definition are used as the units of the media definition keyword sections:
- SIZE (width and height values)
- PRINTAREA (x, y, width and height values)
- RESTRICTED (x, y, width and height values)
NOTE: The origin for coordinate based systems is (0,0). The origin for row/column based systems can be (0,0) or (1,1) and must be configurable within the Service Provider.
11.2.4.3 - Form Definition
Attributes are not required in any mandatory order within a Form definition.
| XFSFORM | |||
|---|---|---|---|
| XFSFORM | formname* | ||
| BEGIN | |||
| (required) | UNIT | base, | Base resolution unit for form definition: MM INCH ROWCOLUMN |
| x, | Horizontal base unit fraction | ||
| y | Vertical base unit fraction | ||
| (required) | SIZE | width, | Width of form |
| height | Height of form | ||
| (required) | ALIGNMENT | alignment, | Alignment of the form on the physical media (TOPLEFT (default), TOPRIGHT, BOTTOMLEFT, BOTTOMRIGHT). This option allows the positioning of a form onto a physical page relative to any combination of the edges of the physical media, to support the variations in how devices sense the edge of page for positioning purposes. |
| xoffset, | Horizontal offset relative to the horizontal alignment specified by alignment. Always specified as a positive value (i.e. if aligned to the right side of the media, means offset the form to the left). (default = 0) | ||
| yoffset | Vertical offset relative to the vertical alignment specified by alignment. Always specified as a positive value (i.e. if aligned to the bottom of the media, means offset the form upward). (default = 0) | ||
| ORIENTATION | type | Orientation of form: PORTRAIT (default) LANDSCAPE |
|
| SKEW | skewfactor | Maximum skew factor in degrees (default = 0) | |
| VERSION | major, | Major version number | |
| minor, | Minor version number | ||
| date*, | Creation/modification date | ||
| author* | Author of the form | ||
| CPI | cpi | Characters per inch. This value specifies the default CPI within the form. When the ROWCOLUMN unit is used, the form CPI and LPI are used to calculate the position and size of all fields within a form, irrespective of the CPI and LPI of the fields themselves. | |
| LPI | lpi | Lines per inch. This value specifies the default LPI within the form. When the ROWCOLUMN unit is used, the form CPI and LPI are used to calculate the position and size of all fields within a form, irrespective of the CPI and LPI of the fields themselves. | |
| POINTSIZE | pointsize | This value specifies the default POINTSIZE within the form. | |
| COPYRIGHT | copyright* | Copyright entry | |
| TITLE | title* | Title of form | |
| COMMENT | comment* | Comment section | |
| USERPROMPT | prompt* | Prompt string for user interaction | |
| [XFSFIELD BEGIN ... END] |
fieldname* | One field definition (as defined in the next section) for each field in the form. The fieldname within a form and its optional subforms must be unique. | |
| [XFSFRAME BEGIN ... END] |
framename* | One frame definition (as defined in the next section) for each frame in the form. The framename within a form and its optional subforms must be unique. | |
| [XFSSUBFORM BEGIN ... END] |
subformname* | One subform definition (as defined in the next section) for each subform in the form. The subformname within a form must be unique. | |
| END |
11.2.4.4 - SubForm Definition
| XFSSUBFORM | |||
|---|---|---|---|
| XFSSUBFORM | subformname* | ||
| BEGIN | |||
| (required) | POSITION | x, | Horizontal position (relative to left side of form) |
| y or (y, z) | Vertical position (relative to top of form). Format (y, z) is used to indicate vertical positioning relative to top of form when top of form is other than 1st page of form, where Z indicates page number (relative to 0) and Y indicates base resolution units relative to top of the form page number (as indicated by Z). Format y is used to indicate vertical positioning relative to top of the 1st form page. | ||
| (required) | SIZE | width, | Width of subform. Width must not exceed width of form. |
| height | Height of subform. Height must not exceed height of form. | ||
| [XFSFIELD BEGIN ... END] |
fieldname* | One field definition (as defined in the next section) for each field in the form. The fieldname within a form and its optional subforms must be unique. | |
| [XFSFRAME BEGIN ... END] |
framename* | One frame definition (as defined in the next section) for each frame in the form. The framename within a form and its optional subforms must be unique. | |
| END |
The XFSSUBFORM definition provides a means to isolate a selected area of a form where the user may want to have a select group of fields, frames, and/or running headers and footers. All field and frame definitions within a subform are relative to the POSITION of the subform. A form definition with an imbedded subform will have a series of statements illustrated as follows:
XFSFORM
BEGIN
*
*
XFSSUBFORM
BEGIN
XFSFIELD
BEGIN
*
*
END
XFSFIELD
BEGIN
*
*
END
END
END
11.2.4.5 - Field Definition
| XFSFIELD | |||
|---|---|---|---|
| XFSFIELD | fieldname* | The fieldname within a form and its optional subforms must be unique. | |
| BEGIN | |||
| (required) | POSITION | x, | Horizontal position (relative to left side of form/subform). |
| y or (y, z) | Vertical position (relative to top of form/subform). Format (y, z) is used to indicate vertical positioning relative to top of form/subform when top of form/subform is other than 1st page of form/subform, where z indicates page number (relative to 0) and y indicates base resolution units relative to top of the form/subform page number (as indicated by z). Format y is used to indicate vertical positioning relative to top of the 1st form/subform. | ||
| FOLLOWS | fieldname* | Print this field directly following the field with the name fieldname; positioning information is ignored. See the description of Printer.PrintForm. If FOLLOWS is omitted, then fields are printed in the order that they appear in the form definition. | |
| HEADER | N | This field is either a form/subform header field. N represents a form/subform page number (relative to 0) the header field is to print within. | |
| N-N | N-N represents a form/subform page number range the header field is to print within. Combinations of N and N-N may exist separated by commas. | ||
| ALL | ALL indicates that header field is to be printed on all pages of form/subform. The form/subform page number is intended to supplement the Z parameter of the POSITION keyword. For example, 0,2-4,6 indicates that the header field is to print on relative form/subform pages 0, 2, 3, 4, and 6. | ||
| HEADER | N | This field is either a form/subform header field. N represents a form/subform page number (relative to 0) the header field is to print within. | |
| N-N | N-N represents a form/subform page number range the header field is to print within. Combinations of N and N-N may exist separated by commas. | ||
| ALL | ALL indicates that header field is to be printed on all pages of form/subform. The form/subform page number is intended to supplement the Z parameter of the POSITION keyword. For example, 0,2-4,6 indicates that the header field is to print on relative form/subform pages 0, 2, 3, 4, and 6. | ||
| FOOTER | N | This field is either a form/subform footer field. N represents a form/subform page number (relative to 0) the footer field is to print within. | |
| N-N | N-N represents a form/subform page number range the footer field is to print within. Combinations of N and N-N may exist separated by commas. | ||
| ALL | ALL indicates that footer field is to be printed on all pages of form/subform. The form/subform page number is intended to supplement the Z parameter of the POSITION keyword. For example, 0,2-4,6 indicates that the footer field is to print on relative form/subform pages 0, 2, 3, 4, and 6. | ||
| SIDE | side | Side of form where field is positioned: FRONT (default) BACK |
|
| (required) | SIZE | width, | Field width. |
| height | Field height. | ||
| INDEX | repeatcount | Count how often this field is repeated in the form, INDEX fields are fixed length (default is no INDEX field). | |
| xoffset, | Horizontal offset for next field. | ||
| yoffset | Vertical offset for next field. | ||
| TYPE | fieldtype | Type of field: TEXT (default) MICR OCR MSF BARCODE GRAPHIC PAGEMARK |
|
| SCALING | scalingtype | Information on how to size the GRAPHIC within GRAPHIC field types: BESTFIT (default): Scale to size indicated. ASIS: Render at native size. MAINTAINASPECT: scale as close as possible to size indicated while maintaining the aspect ratio and not losing graphic information. |
|
| BARCODE | hriposition | Position of the HRI (Human Readable Interpretation) characters: NONE (default) ABOVE BELOW BOTH The type of barcode to print is defined in the FONT field. |
|
| COERCIVITY | coercivity | Coercivity to be used for writing to the magnetic stripe of MSF field types: AUTO (default): Coercivity is decided by the Service Provider or hardware. LOW: Low coercivity. HIGH: High coercivity. |
|
| CLASS | class | Field class: OPTIONAL (default) STATIC REQUIRED |
|
| ACCESS | access | Access rights of field: WRITE (default) READ READWRITE |
|
| OVERFLOW | overflow | Action of field overflow: TERMINATE (default) TRUNCATE BESTFIT (The Service Provider fits the data into the field as well as it can) OVERWRITE (a contiguous write) WORDWRAP |
|
| STYLE | style | Display attributes as a combination, using the | operator, of the following: NORMAL (default) BOLD ITALIC UNDER (single underline) DOUBLEUNDER (double underline) DOUBLE (double width) TRIPLE (triple width) QUADRUPLE (quadruple width) STRIKETHROUGH ROTATE90 (rotate 90 degrees clockwise) ROTATE270 (rotate 270 degrees clockwise) UPSIDEDOWN (upside down) PROPORTIONAL (proportional spacing) DOUBLEHIGH TRIPLEHIGH QUADRUPELHIGH CONDENSED SUPERSCRIPT OVERSCORE LETTERQUALITY NEARLETTERQUALITY DOUBLESTRIKE OPAQUE (If omitted then the default attribute is transparent) Some of these styles may be mutually exclusive or may combine to provide unexpected results. |
|
| CASE | case | Convert field contents to: NOCHANGE (default) UPPER LOWER |
|
| HORIZONTAL | justify | Horizontal alignment of field contents: LEFT (default) RIGHT CENTER JUSTIFY |
|
| VERTICAL | justify | Vertical alignment of field contents: BOTTOM (default) CENTER TOP |
|
| COLOR | color | Color name: BLACK (default) WHITE GRAY RED BLUE GREEN YELLOW |
|
| RGBCOLOR | R, G, B | Color in RGB 8 bits per color format: R: Red portion of the RGB value 0-255. G: Green portion of the RGB value 0-255. B: Blue portion of the RGB value 0-255. RGBCOLOR overrides the COLOR attribute. |
|
| FONT | fontname* | Font name: This attribute is interpreted by the Service Provider. In some cases, it may indicate printer resident fonts, and in others it may indicate the name of a downloadable font. For BARCODE fields it represents the barcode font name. In some cases, this pre-defines the following parameters: | |
| POINTSIZE | pointsize | Point size. If unspecified, the point size defaults to the POINTSIZE defined for the form. | |
| CPI | cpi | Characters per inch. If unspecified, the CPI defaults to the CPI defined for the form. | |
| LPI | lpi | Lines per inch. If unspecified, the LPI defaults to the LPI defined for the form. | |
| FORMAT | formatstring* | This is a client defined input field describing how the client should format the data. This may be interpreted by the Service Provider. | |
| INITIALVALUE | value* | Initial value. For GRAPHIC type fields, this value may contain the filename of the graphic image. The type of this graphic will be determined by the file extension (e.g. BMP for Windows Bitmap). Graphic file name may be full or partial path. For example, “C:\BSVC\BSVCLOGO.BMP” illustrates use of full path name. A file name specification of “LOGO.BMP” illustrates partial path name. In this instance file is obtained from current directory. Graphic contents can be changed dynamically at run-time and the new content will be printed on the next print action. | |
| END |
The following diagrams illustrate the positioning and sizing of text fields on a form, and the vertical alignment of text within a field using VERTICAL=TOP and VERTICAL=BOTTOM values in the field definition.
Definition of the character drawing box:
When more than one line of text is to be printed in a field, and the definition includes VERTICAL=BOTTOM, the vertical position of the first line is calculated using the specified (or implied) LPI value.
11.2.4.6 - Frame Definition
| XFSFRAME | |||
|---|---|---|---|
| XFSGRAME | framename* | ||
| BEGIN | |||
| (required) | POSITION | X, | Horizontal position of top left corner of the frame (relative to left side of form/subform). |
| Y or (Y, Z) | Vertical position of top left corner of frame (relative to top of form/subform). Format (Y, Z) is used to indicate vertical positioning of the top left corner of the frame relative to top of form/subform when top of form/subform is other than 1st page of form/subform, where Z indicates page number (relative to 0) and Y indicates base resolution units relative to top of the form/subform page number (as indicated by Z). Format Y is used to indicate vertical positioning of the left corner of frame relative to top of the 1st form/subform. | ||
| FRAMES | fieldname* | Frames the field with the name fieldname, positioning and size information are ignored. The frame surrounds the complete field, not just the printed data. If the field is repeated, the frame surrounds the first and last fields that are printed. | |
| HEADER | N | This frame is either a form/subform header frame. N represents a form/subform page number (relative to 0) the header frame is to print within. | |
| N-N | N-N represents a form/subform page number range the header frame is to print within. Combinations of N and N-N may exist separated by commas. | ||
| ALL | ALL indicates that header frame is to be printed on all pages of form/subform. The form/subform page number is intended to supplement the Z parameter of the POSITION keyword. For example, 0,2-4,6 indicates that the header frame is to print on relative form/subform pages 0, 2, 3, 4, and 6. | ||
| FOOTER | N | This frame is either a form/subform footer frame. N represents a form/subform page number (relative to 0) the footer frame is to print within. | |
| N-N | N-N represents a form/subform page number range the footer frame is to print within. Combinations of N and N-N may exist separated by commas. | ||
| ALL | ALL indicates that footer frame is to be printed on all pages of form/subform. The form/subform page number is intended to supplement the Z parameter of the POSITION keyword. For example, 0,2-4,6 indicates that the footer frame is to print on relative form/subform pages 0, 2, 3, 4, and 6. | ||
| SIDE | side | Side of form where this frame is positioned: FRONT (default) BACK |
|
| (required) | SIZE | width, | Frame width in base horizontal units for the form. |
| height | Frame height in base vertical units for the form. | ||
| REPEATONX | repeatcount, | Count how often this frame is repeated horizontally in the form. | |
| xoffset | Horizontal offset for next frame in base horizontal units. | ||
| REPEATONY | repeatcount, | Count how often this frame is repeated vertically in the form. | |
| yoffset | Vertical offset for next frame in base vertical units. | ||
| TYPE | frametype | Type of frame: RECTANGLE (default) ROUNDED_CORNER ELLIPSE |
|
| CLASS | class | Frame class: STATIC (default) OPTIONAL (The frame is printed only if its name appears in the list of field names given as parameter to the Printer.PrintForm command. In this case, the name of the frame must be different from all the names of the fields.) |
|
| OVERFLOW | overflow | Action on frame overflowing the form: TERMINATE (default) TRUNCATE BESTFIT (the Service Provider fits the frame into the media as well as it can) |
|
| STYLE | style | Frame line attributes: SINGLE_THIN (default) DOUBLE_THIN SINGLE_THICK DOUBLE_THICK DOTTED |
|
| COLOR | color | Color name for frame lines: BLACK (default) WHITE GRAY RED BLUE GREEN YELLOW |
|
| RGBCOLOR | R, G, B | Color in RGB 8 bits per color format: R: Red portion of the RGB value 0-255. G: Green portion of the RGB value 0-255. B: Blue portion of the RGB value 0-255. RGBCOLOR overrides the COLOR attribute. |
|
| FILLCOLOR | color | Color name for interior of frame: BLACK WHITE (default) GRAY RED BLUE GREEN YELLOW |
|
| RGBFILLCOLOR | R, G, B | Color in RGB 8 bits per color format: R: Red portion of the RGB value 0-255. G: Green portion of the RGB value 0-255. B: Blue portion of the RGB value 0-255. RGBFILLCOLOR overrides the FILLCOLOR attribute. |
|
| FILLSTYLE | style | Style for filling the interior of frame: NONE (default): No fill SOLID: Solid color BDIAGONAL: Downward hatch (left to right) at 45 degrees CROSS: Horizontal and vertical crosshatch DIAGCROSS: Crosshatch at 45 degrees FDIAGONAL: Upward hatch (left to right) at 45 degrees HORIZONTAL: Horizontal hatch VERTICAL: Vertical hatch |
|
| SUBSTSIGN | substitute sign | Character that is used as substitute sign when a character in a read field cannot be read | |
| TITLE | fieldname* | Uses the field with the name |
|
| HORIZONTAL | justify | Horizontal alignment of the frame title: LEFT (default) CENTER RIGHT |
|
| VERTICAL | justify | Vertical alignment of the frame title: TOP (default) BOTTOM |
|
| END |
The XFSFRAME definition provides a means for framing a XFSFIELD text field. The basic concept of a XFSFRAME definition and corresponding XFSFIELD definition is illustrated as follows:
When the XFSFRAME frames a field, its positioning and size information are ignored. Instead, Service Providers should position the top left corner of the frame one horizontal base unit to the left and one vertical base unit to the top of the top left corner of the field. Similarly, Service Providers should size the frame so that it bottom right corner is one base unit below and to the right to the field. For instance, if the form units are ROWCOLUMN, and a XFSFRAME “A” is said to frame the XFSFIELD “B” which is positioned at row 1, column 1 with a size of 1 row and 20 columns, the frame will be drawn from row 0, column 0 to row 3, column 22.
The horizontal and vertical positioning of a frame title overrides the position of the named XFSFIELD. For instance, if a XFSFRAME “A” is said to have the XFSFIELD “B” as its title, with the default horizontal and vertical title justification, it is just as if XFSFIELD “B” had been positioned at the top left corner of the frame. Note that the SIZE information for the title field still is meaningful; it gives the starting and/or ending positions of the frame lines.
The SIDE attributes of the XFSFRAME and the XFSFIELDs it refers to must agree.
The width of the lines and the interval between the lines of doubled frames are vendor specific. Whether the lines are drawn using graphics printing or using pseudo-graphic is vendor specific. However, Service Providers are responsible for rendering intersecting frames.
Depending on the printer technology, framing of fields can substantially slow down the print process.
Support of framing by a Service Provider or the device it controls is not mandatory to be XFS compliant.
11.2.4.6.1 - Sample 1 - Simple Framing
The form:
XFSFORM "Multiple Balances"
BEGIN
UNIT INCH, 16, 16
SIZE 91, 64
VERSION 1, 0, "13/09/96", "XFS"
LANGUAGE 0x0409
XFSFIELD "Account Title"
BEGIN
POSITION 15, 4
SIZE 30, 4
CLASS STATIC
HORIZONTAL CENTER
INITIALVALUE "Account"
END
XFSFIELD "Balance Title"
BEGIN
POSITION 45, 4
SIZE 30, 4
CLASS STATIC
HORIZONTAL CENTER
INITIALVALUE "Balance"
END
XFSFIELD "Account"
BEGIN
POSITION 15, 8
SIZE 30, 4
INDEX 10, 0, 3
END //"Account"
XFSFIELD "Balance"
BEGIN
POSITION 45, 8
SIZE 30, 4
INDEX 10, 0, 3
HORIZONTAL RIGHT
END //"Balance"
XFSFRAME "Account Title"
BEGIN
POSITION 15, 4
FRAMES "Account Title"
SIZE 30, 4
STYLE DOUBLE_THIN
END
XFSFRAME "Balance Title"
BEGIN
POSITION 45, 4
FRAMES "Balance Title"
SIZE 30, 4
STYLE DOUBLE_THIN
END
XFSFRAME "Account"
BEGIN
POSITION 15, 8
FRAMES "Account"
SIZE 30, 34
STYLE DOUBLE_THIN
END
XFSFRAME "Balance"
BEGIN
POSITION 45, 8
FRAMES "Balance"
SIZE 30, 34
STYLE DOUBLE_THIN
END
END
When printed with the following field list:
Account[0]=0123456789123001
Account[1]=0123456789123002
Account[2]=0123456789123003
Balance[0]=$17465.12
Balance[1]=$2458.23
Balance[2]=$6542.78
Will print:
11.2.4.6.2 - Sample 2 - Framing With Title
The form:
XFSFORM "Bank Details"
BEGIN
UNIT INCH, 16, 16
SIZE 121, 64
VERSION 1, 0, "13/09/96", "XFS Editor"
LANGUAGE 0x0409
XFSFIELD "Owner Frame Title"
BEGIN
POSITION 24, 9
SIZE 27, 3
CLASS STATIC
HORIZONTAL CENTER
VERTICAL CENTER
INITIALVALUE "Account Owner"
END
XFSFIELD "Owner"
BEGIN
POSITION 20, 11
SIZE 35, 9
CLASS REQUIRED
VERTICAL TOP
END //"Owner"
XFSFRAME "Owner Frame"
BEGIN
POSITION 19, 10
FRAMES "Owner"
SIZE 37, 11
TITLE "Owner Frame Title"
HORIZONTAL CENTER
END
END
When printed with the following field list:
Owner = Mr./Mrs. Jean Leroy
21560 Hagerty Road
Troy, MI.
Will print:
11.2.4.6.3 - Sample 3 - Framing With Filled Interior
The form:
XFSFORM "Bank Details"
BEGIN
UNIT INCH, 16, 16
SIZE 121, 64
VERSION 1, 0, "13/09/96", "XFS Editor"
LANGUAGE 0x0409
XFSFIELD "Owner"
BEGIN
POSITION 20, 11
SIZE 35, 9
CLASS REQUIRED
VERTICAL TOP
END
XFSFRAME "Owner Frame"
BEGIN
POSITION 19, 10
FRAMES "Owner"
SIZE 37, 11
FILLCOLOR GRAY
FILLSTYLE CROSS
END
END
When printed with the following field list:
Owner = Mr./Mrs. Jean Leroy
21560 Hagerty Road
Troy, MI.
Will print:
11.2.4.6.4 - Sample 4 - Repeated Framing
The form:
XFSFORM "Smart Account Number"
BEGIN
UNIT INCH, 16, 16
SIZE 121, 64
VERSION 1, 0, "13/09/96", "XFS Editor"
LANGUAGE 0x0409
XFSFIELD "Account Number"
BEGIN
POSITION 20, 8
SIZE 4, 4
INDEX 12, 4, 0
HORIZONTAL CENTER
VERTICAL CENTER
END
XFSFRAME "A/N Frame"
BEGIN
POSITION 20, 8
SIZE 4, 4
REPEATONX 12, 4
END
END
When printed with the following field list:
Account Number[0]=0
Account Number[1]=1
Account Number[2]=2
Account Number[3]=3
Account Number[4]=4
Account Number[5]=5
Account Number[6]=6
Account Number[7]=7
Account Number[8]=8
Account Number[9]=9
Account Number[10]=0
Account Number[11]=1
Will print:
11.2.4.7 - Media Definition
The media definition determines those characteristics that result from the combination of a particular media type together with a particular vendor's printer. The aim is to make it easy to move forms between different vendors' printers which might have different constraints on how they handle a specific media type. It is the Service Provider's responsibility to ensure that the form definition does not specify the printing of any fields that conflict with the media definition. An example of such a conflict might be that the form definition asks for a field to be printed in an area that the media definition defines as an unprintable area.
The media definition is also intended to provide the capability of defining media types that are specific to the financial industry. An example is a passbook as shown below.
| XFSMEDIA | |||
|---|---|---|---|
| XFSMEDIA | medianame* | ||
| BEGIN | |||
| TYPE | type | Predefined media types are: GENERIC (default) MULTIPART PASSBOOK |
|
| SOURCE | source | Paper source: ANY (default) UPPER LOWER EXTERNAL (envelope tray or single sheet feed tray) AUX AUX2 PARK |
|
| (required) | UNIT | base, | Base resolution unit for form definition: MM INCH ROWCOLUMN |
| x, | Horizontal base unit fraction | ||
| y | Vertical base unit fraction | ||
| (required) | SIZE | width, | Width of physical media |
| height | Height of physical media (0 = unlimited, i.e. roll paper) | ||
| PRINTAREA | x, | Printable area relative to top left corner of physical media (default = physical size of media) | |
| y, | |||
| width, | |||
| height | |||
| RESTRICTED | x, | Restricted area relative to top left corner of physical media (default = no restricted area) | |
| y | |||
| width, | |||
| height | |||
| FOLD | fold, | Type of passbook: HORIZONTAL (default) VERTICAL |
|
| STAGGERING | staggering | Staggering of passbook from top (default = 0) | |
| PAGE | count | Number of pages in passbook (default = 0) | |
| LINES | count | Number of printable lines (default = 0) | |
| END |
11.2.4.8 - XFS Form/Media Definition Files in Multi-Vendor Environments
Although for most Service Providers directory location and extension of XFS form/media definition files are configurable through the registry, the capabilities of Service Providers and or actual hardware may vary. Therefore, the following considerations should be taken into account when clients use XFS form definition files with the purpose of running in a multi-vendor environment:
-
Physical print area dimensions of printers are not identical.
-
Graphic printout may not be supported, which may limit the use of the FONT, CPI and LPI keywords.
-
Some printers may have a resolution of dots/mm rather than dots/inch, which may result in printouts with a specific CPI/LPI font resolution to be slightly off size.
-
Some form/media definition keywords may not be supported due to limitations of the hardware or software.
11.2.5 - Command and Event Flows during Single and Multi-Page / Wad Printing
It is possible to print a number of pages or bunches of pages (wads) through the XFS Service Provider. The following sections describe how this is achieved.
11.2.5.1 - Single Page / Single Wad Printing With Immediate Media Control
This diagram illustrates the command and event flows in a successful print command (i.e. Printer.PrintRawFile, Printer.PrintForm and Printer.RawData) where the following conditions apply:
-
A single page or single wad of pages is presented.
-
The mediaPresented Capability flag is true (indicates that the Printer.MediaPresentedEvent event can be generated).
-
The mediaControl flag in the command data is set to eject. The Printer.PrintRawFile command is used as an example.
11.2.5.2 - Single Page / Single Wad Printing With Separate Media Control
This diagram illustrates the command and event flows in a successful print command (i.e. Printer.PrintRawFile, Printer.PrintForm and Printer.RawData) where the following conditions apply:
-
A single page or single wad of pages is presented.
-
The mediaPresented Capability flag is true (indicates that the Printer.MediaPresentedEvent event can be generated).
-
The mediaControl flag is not included in the command data. The Printer.PrintRawFile command is used as an example.
-
The media is presented to the user through a Printer.ControlMedia command, with the mediaControl parameter set to eject.
11.2.5.3 - Multi Page / Multi Wad Printing With Immediate Media Control
This diagram illustrates a successful Printer.PrintRawFile command where multiple page/wads are presented (and the mediaPresented capability indicates that the Printer.MediaPresentedEvent can be generated). In addition, the previous page/wad must be removed before subsequent pages/wads can be printed.
The diagram illustrates the command and event flows in a successful print command where the following conditions apply:
-
Multiple pages or multiple wads of pages are presented.
-
The mediaPresented capability is true (indicates that the Printer.MediaPresentedEvent event can be generated).
-
The mediaControl flag in the command data is set to eject.
-
The previous page/wad must be removed before subsequent pages/wads can be presented.
11.2.5.4 - Multi Page / Multi Wad Printing With Separate Media Control
This diagram illustrates a successful Printer.PrintRawFile command where multiple page / wads are presented (and the mediaPresented capability indicates that the Printer.MediaPresentedEvent can be generated). In addition, the previous page/wad must be removed before subsequent pages/wads can be printed.
The diagram illustrates the command and event flows in a successful print command where the following conditions apply:
-
Multiple pages or multiple wads of pages are presented.
-
The mediaPresented capability is true (indicates that the Printer.MediaPresentedEvent event can be generated).
-
The mediaControl flag command data is omitted.
-
The media is presented to the user through a Printer.ControlMedia command, with the mediaControl property set to eject.
-
The previous page/wad must be removed before subsequent pages/wads can be presented.
11.3 - Command Messages
11.3.1 - Printer.GetFormList
This command is used to retrieve the list of forms available on the device.
Command Message
Completion Message
Event Messages
None11.3.2 - Printer.GetMediaList
This command is used to retrieve the list of media definitions available on the device.
Command Message
Completion Message
Event Messages
None11.3.3 - Printer.GetQueryForm
This command is used to retrieve details of the definition of a specified form.
Command Message
Completion Message
Event Messages
None11.3.4 - Printer.GetQueryMedia
This command is used to retrieve details of the definition of a specified media.
Command Message
Completion Message
Event Messages
None11.3.5 - Printer.GetQueryField
This command is used to retrieve details of the definition of a single or all fields on a specified form.
Command Message
Completion Message
Event Messages
None11.3.6 - Printer.GetCodelineMapping
This command is used to retrieve the byte code mapping for the special banking symbols defined for image processing (e.g. check processing). This mapping must be reported as there is no standard for the fonts defined below.
Command Message
Completion Message
Event Messages
None11.3.7 - Printer.ControlMedia
This command is used to control media.
If an eject operation is specified, it completes when the media is moved to the exit slot. An unsolicited event is generated when the media has been taken by the user (only if the mediaTaken capability is true.
Command Message
Completion Message
Event Messages
11.3.8 - Printer.PrintForm
This command is used to print a form by merging the supplied variable field data with the defined form and field data specified in the form. If no media is present, the device waits, for the period of time specified by the timeout parameter, for media to be inserted from the external paper source.
All error codes (except noMediaPresent) and events listed under the Printer.ControlMedia command description can also occur on this command.
An invalid field name is treated as a Printer.FieldWarningEvent event with failure notfound. A Printer.FieldWarningEvent event is returned with fieldOverflow status if the data overflows the field, and the field definition OVERFLOW value is TRUNCATE, BESTFIT, OVERWRITE or WORDWRAP. Other field-related problems generate a field error return and event.
Command Message
Completion Message
Event Messages
- Printer.NoMediaEvent
- Printer.MediaInsertedEvent
- Printer.FieldErrorEvent
- Printer.FieldWarningEvent
- Printer.RetractBinThresholdEvent
- Printer.MediaTakenEvent
- Printer.PaperThresholdEvent
- Printer.TonerThresholdEvent
- Printer.InkThresholdEvent
- Printer.MediaPresentedEvent
- Printer.MediaRejectedEvent
- Printer.MediaAutoRetractedEvent
11.3.9 - Printer.ReadForm
This command is used to read data from input fields on the specified form. These input fields may consist of MICR, OCR, MSF, BARCODE, or PAGEMARK input fields. These input fields may also consist of TEXT fields for purposes of detecting available passbook print lines with passbook printers supporting such capability. If no media is present, the device waits, for the timeout specified, for media to be inserted.
All error codes (except noMediaPresent) and events listed under the Printer.ControlMedia command description can also occur on this command.
The following applies to the usage of fields for passbook:
If the media type is PASSBOOK, and the field(s) type is TEXT, and the Service Provider and the underlying passbook
printer are capable of detecting available passbook print lines, then the field(s) will be returned without a
value, in the format "
To illustrate when media type is PASSBOOK, if a form named PSBKTST1 contains 24 fields, one field per line, and the field names are LINE1 through LINE24 (same order as printing), and after execution of this command fields contains fields LINE13 through LINE24, then the first print line available for passbook printing is line 13.
To illustrate another example when media type is PASSBOOK, if a form named PSBKTST2 contains 24 fields, one field per line, and the field names are LINE1 through LINE24 (same order as printing), and after execution of this command fields contains fields LINE13, and LINE20 through LINE24 then the first print line available for passbook printing is line 13, however lines 14-19 are not also available, so if the client is attempting to determine the first available print line after which all subsequent print lines are also available then line 20 is a better choice.
Command Message
Completion Message
Event Messages
11.3.10 - Printer.RawData
This command is used to send raw data (a byte string of device dependent data) to the physical device.
Clients which send raw data to a device will typically not be device or vendor independent. Problems with the use of this command include:
- The data sent to the device can include commands that change the state of the device in unpredictable ways (in particular, in ways that the Service Provider may not be aware of).
- Usage of this command will not be portable.
- This command violates the XFS forms model that is the basis of XFS printer access.
Thus usage of this command should be avoided whenever possible.
Command Message
Completion Message
Event Messages
11.3.11 - Printer.MediaExtents
This command is used to get the extents of the media inserted in the physical device. The input parameter specifies the base unit and fractions in which the media extent values will be returned. If no media is present, the device waits, for the timeout specified, for media to be inserted.
Command Message
Completion Message
Event Messages
11.3.12 - Printer.ResetCount
This function resets the present value for number of media items retracted to zero. The function is possible only for printers with retract capability.
The number of media items retracted is controlled by the service and can be requested before resetting using the info Common.Status command.
Command Message
Completion Message
Event Messages
11.3.13 - Printer.ReadImage
This function returns image data from the current media. If no media is present, the device waits for the timeout specified, for media to be inserted.
If the returned image data is in Windows bitmap format (BMP) and a file path for storing the image is not supplied, then the first byte of data will be the start of the Bitmap Info Header (this bitmap format is known as DIB, Device Independent Bitmap). The Bitmap File Info Header, which is only present in file versions of bitmaps, will NOT be returned. If the returned image data is in bitmap format (BMP) and a file path for storing the image is supplied, then the first byte of data in the stored file will be the Bitmap File Info Header.
Command Message
Completion Message
Event Messages
11.3.14 - Printer.Reset
This command is used by the client to perform a hardware reset which will attempt to return the device to a known good state.
The device will attempt to retract or eject any items found anywhere within the device. This may not always be possible because of hardware problems. The Printer.MediaDetectedEvent event will inform the client where items were actually moved to.
Command Message
Completion Message
Event Messages
11.3.15 - Printer.RetractMedia
The media is removed from its present position (media inserted into device, media entering, unknown position) and stored in one of the retract bins. An event is sent if the storage capacity of the specified retract bin is reached. If the bin is already full and the command cannot be executed, an error is returned and the media remains in its present position.
If a retract request is received for a device with no retract capability, the unsupportedCommand error is returned.
Command Message
Completion Message
Event Messages
11.3.16 - Printer.DispensePaper
This command is used to move paper (which can also be a new passbook) from a paper source into the print position.
Command Message
Completion Message
Event Messages
11.3.17 - Printer.PrintRawFile
This command is used to print a file that contains a complete print job in the native printer language. The creation and content of this file are both Operating System and printer specific and outwith the scope of this specification.
If no media is present, the device waits, for the timeout specified, for media to be inserted from the external paper source.
This command must not complete until all pages have been presented to the customer.
Printing of multiple pages is handled as described in Command and Event Flows during Single and Multi-Page / Wad Printing.
Command Message
Completion Message
Event Messages
11.3.18 - Printer.LoadDefinition
This command is used to load a form (including sub-forms and frames) or media definition into the list of available forms. Once a form or media definition has been loaded through this command it can be used by any of the other form/media definition processing commands. Forms and media definitions loaded through this command are persistent. When a form or media definition is loaded a Printer.DefinitionLoadedEvent event is generated to inform clients that a form or media definition has been added or replaced.
Command Message
Completion Message
Event Messages
11.3.19 - Printer.SupplyReplenish
After the supplies have been replenished, this command is used to indicate that one or more supplies have been replenished and are expected to be in a healthy state.
Hardware that cannot detect the level of a supply and reports on the supply's status using metrics (or some other means), must assume the supply has been fully replenished after this command is issued. The appropriate threshold event must be broadcast.
Hardware that can detect the level of a supply must update its status based on its sensors, generate a threshold event if appropriate, and succeed the command even if the supply has not been replenished. If it has already detected the level and reported the threshold before this command was issued, the command must succeed and no threshold event is required.
If any one of the specified supplies is not supported by a Service Provider, unsupportedData should be returned, and no replenishment actions will be taken by the Service Provider.
Command Message
Completion Message
Event Messages
11.3.20 - Printer.ControlPassbook
This command can turn the pages of a passbook inserted in the printer by a specified number of pages in a specified direction and it can close the passbook. The controlPassbook field returned by Common.Capabilities specifies which functionality is supported. This command flushes the data before the pages are turned or the passbook is closed.
Command Message
Completion Message
Event Messages
None11.3.21 - Printer.SetBlackMarkMode
This command switches the black mark detection mode and associated functionality on or off. The black mark detection mode is persistent. If the selected mode is already active this command will complete with success.
Command Message
Completion Message
Event Messages
None11.4 - Event Messages
11.4.1 - Printer.MediaPresentedEvent
This event is used to indicate when media has been presented to the customer for removal.
11.4.2 - Printer.NoMediaEvent
This event specifies that the physical media must be inserted into the device in order for the execute command to proceed.
11.4.3 - Printer.MediaInsertedEvent
This event specifies that the physical media has been inserted into the device.
The client may use this event to, for example, remove a message box from the screen telling the user to insert media.
11.4.4 - Printer.FieldErrorEvent
This event specifies that a fatal error has occurred while processing a field.
11.4.5 - Printer.FieldWarningEvent
This event specifies that a non-fatal error has occurred while processing a field.
11.4.6 - Printer.MediaRejectedEvent
This event is generated as a result of physical media that is rejected whenever an attempt is made to insert media into the physical device. Rejection of the media will cause the command currently executing to complete with an error, at which point the media should be removed.
The client may use this event to (for example) display a message box on the screen indicating why the media was rejected, and telling the user to remove and reinsert the media.
11.5 - Unsolicited Messages
11.5.1 - Printer.MediaTakenEvent
This event is sent when the media is taken from the exit slot following the completion of a successful eject operation or following a Printer.MediaRejectedEvent. For devices that do not physically move media, this event may also be generated when the media is taken from the device.
11.5.2 - Printer.MediaInsertedUnsolicitedEvent
This event specifies that the physical media has been inserted into the device without any read or print execute commands being executed. This event is only generated when media is entered in an unsolicited manner.
11.5.3 - Printer.MediaPresentedUnsolicitedEvent
This event is used to indicate when media has been presented to the customer for removal as a result of a print operation through some non XFS interface.
11.5.4 - Printer.MediaDetectedEvent
This event is generated when a media is detected in the device during a reset operation.
11.5.5 - Printer.RetractBinStatusEvent
This event specifies that the status of the retract bin holding the retracted media has changed.
11.5.6 - Printer.DefinitionLoadedEvent
This event is used to indicate when a form or media definition has successfully been loaded via the Printer.LoadDefinition command.
11.5.7 - Printer.MediaAutoRetractedEvent
This event indicates when media has been automatically retracted by the device. Support for this event is indicated when autoRetractPeriod is non-zero. The event can be generated as the result of any command that presents media to the customer.
11.5.8 - Printer.RetractBinThresholdEvent
This event specifies that the status of the retract bin holding the retracted media has changed.
11.5.9 - Printer.PaperThresholdEvent
This user event is used to specify that the state of the paper reached a threshold. There is no threshold defined for the parking station as this can contain only one paper item.
11.5.10 - Printer.TonerThresholdEvent
This user event is used to specify that the state of the toner (or ink) reached a threshold.
11.5.11 - Printer.LampThresholdEvent
This user event is used to specify that the state of the imaging lamp reached a threshold.
11.5.12 - Printer.InkThresholdEvent
This user event is used to specify that the state of the stamping ink reached a threshold.
12 - Text Terminal Interface
This chapter defines the Text Terminal interface functionality and messages.
12.1 - Summary
This section describes the functions provided by a generic Text Terminal Unit () service. A Text Terminal Unit is a text i/o device, which applies both to ATM operator panels and to displays incorporated in devices such as pads and printers. This service allows for the following categories of functions:
- Forms oriented input and output
- Direct display output
- Keyboard input
- LED settings and control
All position indexes are zero based, where column zero, row zero is the top-leftmost position.
If the device has no shift key, the TextTerminal.ReadForm and TextTerminal.Read commands will return only upper case letters. If the device has a shift key, these commands return upper and lower case letters as governed by the user's use of the shift key.
12.2 - General Information
12.2.1 - Form and Field Definitions
This section outlines the format of the definitions of forms, the fields within them, and the media on which they are printed.
Definition Syntax
The syntactic rules for form, field and media definitions are as follows:
- White space
space, tab - Line continuation
backslash (\) - Line termination
CR, LF, CR/LF; line termination ends a "keyword section" (a keyword and its value[s]) - Keywords
must be all upper case - Names
(field/media/font names) any case; case is preserved;Service Providers are case sensitive. - Strings
all strings must be enclosed in double quote characters ("); standard C escape sequences are allowed. - Coments
start with two forward slashes (//); end at line termination.
Other notes:
- If a keyword is present, all its values must be specified; default values are used only if the keyword is absent.
- Values that are character strings are marked with asterisks in the definitions below, and must be quoted as specified above.
- Fields are processed in the sequence they are defined in the form.
- The order of attributes within a form is not mandatory; the attributes may be defined in any order.
- All forms can be represented using either ISO 646 (ANSI) or unicode character encoding. If the unicode representation is used then all Names and Strings are restricted to an internal representation of ISO 646 (ANSI) characters. Only the initialValue keyword values can have double byte values outside of the ISO 646 (ANSI) character set.
- If forms character encoding is unicode then, consistent with the unicode standard, the file prefix must be in Little Endian (xFFFE) or Big Endian (xFEFF) notation, such that unicode encoding is recognized.
- In the form definition file, where characters are expressed using standard C hexadecimal escape sequences, the high order byte is defined first. For example, "\x0041" would represent the character 'A'. This is independent of the encoding format of the form definition file
Form/media definition files in multi-vendor environments
Although for most Service Providers directory location and extension of form/media definition files are configurable through the registry, the capabilities of Service Providers and or actual hardware may vary. Therefore the following considerations should be taken into account when clients use form definition files with the purpose of running in a multi-vendor environment:
- Physical display area dimensions may vary from one text terminal to another.
- Just-in-time form loading may not be supported by all Service Providers, which makes it impossible to create dynamic form files just before displaying them (which in return means that only the display data of the forms can be changed, not the -layout data such as field positions).
- Some form/media definition keywords may not be supported due to limitations of the hardware or software.
Form Definition
| FORM | formname* | ||
|---|---|---|---|
| BEGIN | |||
| (required) | SIZE | width height | Width of form Height of form |
| VERSION | major, minor, date*, author* | Major version number (default 0) Minor version number (default 0) Creation/modification date Author of form | |
| (required) | LANGUAGE | languageID | Language used in this form - a 16 bit value (LANGID) which is a combination of a primary (10 bits) and a secondary (6 bits) language ID (This is the standard language ID in the Win32 API; standard macros support construction and decomposition of this composite ID) |
| COPYRIGHT | copyright* | Copyright entry | |
| TITLE | title* | Title of form | |
| COMMENT | comment* | Comment section | |
| [ FIELD | fieldname* | One field definition (as defined in the next section) for each field in the form | |
| BEGIN . . . END ] | |||
| END |
Field Definition
| FIELD | fieldname* | ||
|---|---|---|---|
| BEGIN | |||
| LANGUAGE | languageID | Language used for this field. See Form definition for detailed description. If unspecified defaults to form definition Language specification. | |
| (required) | POSITION | x, y | Horizontal position (relative to left side of form) Vertical position (relative to top of form) The initial left upper position is referenced as (0,0) |
| (required) | SIZE | width, height | Field width Field height |
| TYPE | fieldtype | Type of field: Text (default) Invisible Password (contents is echoed with '*') Graphic (ignored for TextTerminal.ReadForm commands) | |
| SCALING | scalingtype | Information on how to size the Graphic within the field: BestFit (default) scale to size indicated ASIS render at native size Maintainaspect scale as close as possible to size indicated while maintaining the aspect ratio and not losing Graphic information. SCALING is only relevant for Graphics field types | |
| CLASS | class | Field class: Optional (default) Static Required | |
| KEYS | keys | Accepted input key types: Numeric Hexadecimal Alphanumeric This is an optional field where the default value is vendor dependent. | |
| ACCESS | access | Access rights of field: Write (default) Read ReadWrite | |
| OVERFLOW | overflow | Action on field overflow: Terminate (default) Truncate OverWrite | |
| STYLE | style | Display attributes as a combination of the following, ORed together using the " | |
| HORIZONTAL | justify | Horizontal alignment of field contents: Left (default) Right Center | |
| FORMAT | formatstring* | This is a client defined input field describing how the client should format the data. This may be interpreted by the Service Provider. | |
| INITIALVALUE | value* | Initial value. For Graphic type fields, this value will contain the filename of the Graphic image. The type of this Graphic will be determined by the file extension (e.g. BMP for Windows Bitmap). The Graphic file name must contain the full path. For example "C:\XFS\BSVCLOGO.BMP" illustrates the use of the full path name | |
| END |
12.3 - Command Messages
12.3.1 - TextTerminal.GetFormList
This command is used to retrieve the list of forms available on the device.
Command Message
Completion Message
Event Messages
None12.3.2 - TextTerminal.GetQueryForm
This command is used to retrieve details of the definition of a specified form.
Command Message
Completion Message
Event Messages
None12.3.3 - TextTerminal.GetQueryField
This command is used to retrieve details of the definition of a single or all fields on a specified form.
Command Message
Completion Message
Event Messages
None12.3.4 - TextTerminal.GetKeyDetail
This command returns information about the Keys (buttons) supported by the device. This command should be issued to determine which Keys are available.
Command Message
Completion Message
Event Messages
None12.3.5 - TextTerminal.Beep
This command is used to beep at the text terminal unit.
Command Message
Completion Message
Event Messages
None12.3.6 - TextTerminal.ClearScreen
This command clears the specified area of the text terminal unit screen.The cursor is positioned to the upper left corner of the cleared area.
Command Message
Completion Message
Event Messages
None12.3.7 - TextTerminal.DispLight
This command is used to switch the lighting of the text terminal unit on or off.
Command Message
Completion Message
Event Messages
None12.3.8 - TextTerminal.SetLed
This command is used to set the status of the LEDs.
Command Message
Completion Message
Event Messages
None12.3.9 - TextTerminal.SetResolution
This command is used to set the resolution of the display. The screen is cleared and the cursor is positioned at the upper left position.
Command Message
Completion Message
Event Messages
None12.3.10 - TextTerminal.WriteForm
This command is used to display a form by merging the supplied variable field data with the defined form and field data specified in the form.
Command Message
Completion Message
Event Messages
None12.3.11 - TextTerminal.ReadForm
This command is used to read data from input fields on the specified form.
Command Message
Completion Message
Event Messages
None12.3.12 - TextTerminal.Write
This command displays the specified text on the display of the text terminal unit. The specified text may include the control characters CR (Carriage Return) and LF (Line Feed). The control characters can be included in the text as CR, or LF, or CR LF, or LF CR and all combinations will perform the function of relocating the cursor position to the left hand side of the display on the next line down. If the text will overwrite the display area then the display will scroll.
Command Message
Completion Message
Event Messages
None12.3.13 - TextTerminal.Read
This command activates the keyboard of the text terminal unit for input of the specified number of characters. Depending on the specified flush mode the input buffer is cleared. During this command, pressing an active key results in a TextTerminal.KeyEvent event containing the key details. On completion of the command (when the maximum number of keys have been pressed or a terminator key is pressed), the entered string, as interpreted by the Service Provider, is returned. The Service Provider takes command keys into account when interpreting the data.
Command Message
Completion Message
Event Messages
None12.3.14 - TextTerminal.Reset
Sends a service reset to the Service Provider. This command clears the screen, clears the keyboard buffer, sets the default resolution and sets the cursor position to the upper left.
Command Message
Completion Message
Event Messages
None12.3.15 - TextTerminal.DefineKeys
This command defines the keys that will be active during the next TextTerminal.ReadForm command. The configured set will be active until the next TextTerminal.ReadForm command ends, at which point the default values are restored.
Command Message
Completion Message
Event Messages
None12.4 - Unsolicited Messages
12.4.1 - TextTerminal.FieldErrorEvent
This event specifies that a fatal error has occurred while processing a field.
12.4.2 - TextTerminal.FieldWarningEvent
This event is used to specify that a non-fatal error has occurred while processing a field.
12.4.3 - TextTerminal.KeyEvent
This event specifies that any active key has been pressed at the TTU during the TextTerminal.Read command. In addition to giving the client more details about individual key presses this information may also be used if the device has no internal display unit and the client has to manage the display of the entered digits.
13 - Sensors and Indicators Interface
This chapter defines the Sensors and Indicators interface functionality and messages.
13.2 - Command Messages
13.2.1 - SensorsAndIndicators.SetGuidanceLight
This command is used to set the status of the devices guidance lights. This includes defining the flash rate, the color and the direction. When a client tries to use a color or direction that is not supported then the Service Provider will return the generic completionCode unsupportedData.
Command Message
Completion Message
Event Messages
None13.2.2 - SensorsAndIndicators.GetAutoStartupTime
This command is used to retrieve the availability of the auto start-up time function as well as the current configuration of the auto start-up time.
Command Message
Completion Message
Event Messages
None13.2.3 - SensorsAndIndicators.ClearAutoStartupTime
This command is used to clear the time at which the machine will automatically start.
Command Message
Completion Message
Event Messages
None13.2.4 - SensorsAndIndicators.Register
This command is used to register for, or deregister events from the Sensors and Indicators Unit. The default condition is that all events are deregistered. The events are only registered or deregistered for the session which sends the command, all other sessions are unaffected.
No action has been taken if this command returns an error. If a hardware error occurs while executing the command, the command will return OK, but event(s) will be generated which indicate(s) the port(s) which have failed.
Command Message
Completion Message
Event Messages
13.2.5 - SensorsAndIndicators.SetPorts
This command is used to set or clear one or more output ports (indicators) in the Sensors and Indicators Unit.
Command Message
Completion Message
Event Messages
13.2.6 - SensorsAndIndicators.SetDoor
This command is used to set the status of one of the doors.
Command Message
Completion Message
Event Messages
14 - Barcode Reader Interface
This chapter defines the Barcode Reader interface functionality and messages.
14.1 - Summary
A Barcode Reader scans barcodes using any scanning technology. The device logic converts light signals or image recognition into client data and transmits it to the host system.
14.2 - Command Messages
14.2.1 - BarcodeReader.Read
This command enables the barcode reader. The barcode reader will scan for barcodes and when it successfully manages to read one or more barcodes the command will complete. The completion event for this command contains the scanned barcode data.
The device waits for the period of time specified by the timeout parameter for one of the enabled symbologies to be presented, unless the hardware has a fixed timeout period that is less than the value passed in the command.
Command Message
Completion Message
Event Messages
None15 - Card Embosser Interface
This chapter defines the Card Embosser interface functionality and messages.
15.1 - Summary
Embossing card units are generally viewed by XFS as compound devices with the following capabilities and features:
- Embossing or printing of magnetic stripe card/ smart card.
- Reading/encoding magnetic stripe tracks 1, 2, and 3.
- Reading/writing smart card.
- Contactless chip card readers
- LCD display/ keypad input.
The XFS services supporting the various embossing card unit components are outlined as follows:
- Embossing or printing of magnetic stripe card/ smart card - CardEmbosser service.
- Reading / encoding magnetic stripe tracks 1, 2, and 3 - CardReader service, however when combined encoding / embossing is performed the CardEmbosser service class is used.
- Reading / writing smart cards - CardReader service, however when combined writing smart card / embossing is performed the CardEmbosser service class is used.
- LCD display / keypad input - TextTerminal service.
15.2 - General Information
15.2.1 - Embossing Form, Field and Media Definitions
This section outlines the format of the embossing definitions of forms and the fields within them.
15.2.1.1 - Definition Syntax
The syntactic rules for form, field and media definitions are as follows:
- White space
space, tab - Line continuation
backslash (\) - Line termination
CR, LF, CR/LF; line termination ends a “keyword section” (a keyword and its value[s]) - Keywords
must be all upper case - Names
(field/media/font names) any case; case is preserved; Service Providers are case sensitive - Strings
all strings must be enclosed in double quote characters ("); to include a double quote in a string, “escape” with a forward slash (/") - Comments
start with two forward slashes (//), end at line termination
Other Notes:
- If a keyword is present, all its values must be specified; default values are used only if the keyword is absent.
- Values that are character strings are marked with asterisks in the definitions below, and must be quoted as specified above.
- The order of attributes within the forms is not mandatory and the attributes may be defined in any order.
- All forms can be represented using either ISO 646 (ANSI) or UNICODE character encoding. If the UNICODE representation is used then all Names and Strings are restricted to an internal representation of ISO 646 (ANSI) characters. Only the INITIALVALUE and FORMAT keyword values can have double byte values outside of the ISO 646 (ANSI) character set.
- If forms character encoding is UNICODE then, consistent with the UNICODE standard, the file prefix must be in little endian (xFFFE) or big endian (xFEFF) notation, such that UNICODE encoding is recognized.
15.2.1.2 - Embossing Form and Media Measurements
The UNIT keyword sections of the form and media definitions specify the base horizontal and vertical resolution as follows:
- The base value specifies the base unit of measurement.
- The x and y values specify the horizontal and vertical resolution as fractions of the base value (e.g. an x value of 10 and a base value of MM means that the base horizontal resolution is 0.1mm).
The base resolutions thus defined by the UNIT keyword section of the form definition are used as the units of the form definition keyword sections:
- SIZE (width and height values)
- ALIGNMENT (xoffset and yoffset values)
and of the field definition keyword sections:
- POSITION (x and y values)
- SIZE (width and height values)
The base resolutions thus defined by the UNIT keyword section of the media definition are used as the units of the media definition keyword sections:
- SIZE (width and height values)
- EMBOSSAREA (x, y, width and height values)
- RESTRICTED (x, y, width and height values)
15.2.1.3 - Embossing Form Definition
Attributes are not required in any mandatory order within a Form definition.
| XFSFORM | |||
|---|---|---|---|
| XFSFORM | formname | ||
| BEGIN | |||
| (required) | UNIT | base, | Base resolution unit for form definition: MM INCH ROWCOLUMN |
| x, | Horizontal base unit fraction | ||
| y | Vertical base unit fraction | ||
| (required) | SIZE | width, | Width of form |
| height | Height of form | ||
| (required) | ALIGNMENT | alignment, | Alignment of the form on the physical media TOPLEFT (default) TOPRIGHT BOTTOMLEFT BOTTOMRIGHT |
| xoffset, | Horizontal offset relative to the horizontal alignment specified by alignment. Always specified as a positive value (i.e. if aligned to the right side of the media, means offset the form to the left). (default = 0) | ||
| yoffset | Vertical offset relative to the vertical alignment specified by alignment. Always specified as a positive value (i.e. if aligned to the bottom of the media, means offset the form upward). (default = 0) | ||
| VERSION | major, | Major version number | |
| minor, | Minor version number | ||
| date*, | Creation/modification date | ||
| author* | Author of form | ||
| COPYRIGHT | copyright* | Copyright entry | |
| TITLE | title* | Title of form | |
| COMMENT | comment* | Comment section | |
| USERPROMPT | prompt* | Prompt string for user interaction | |
| [XFSFIELD BEGIN ... END] |
fieldname* | One field definition (as defined in the next section) for each field in the form. | |
| END |
15.2.1.4 - Embossing Field Definition
| XFSFIELD | |||
|---|---|---|---|
| XFSFIELD | fieldname | ||
| BEGIN | |||
| (required) | POSITION | x, | Horizontal position (relative to left or right side of form, depending upon HPOSITION keyword) |
| y | Vertical position (relative to top or bottom of form, depending upon VPOSITION keyword) | ||
| HPOSITION | Horizontal field positioning relative to: LEFT (default) RIGHT |
||
| VPOSITION | Vertical field positioning relative to: TOP BOTTOM (default) |
||
| SIDE | side | Side of card: FRONT (default) BACK |
|
| (required) | SIZE | width, | Field width |
| height | Field height | ||
| TYPE | fieldtype | Type of field: TEXT (default) OCR |
|
| CLASS | class | Field class: OPTIONAL (default) STATIC REQUIRED |
|
| CASE | case | Convert field contents to: NOCHANGE (default) UPPER LOWER |
|
| HORIZONTAL | justify | Horizontal alignment of field contents: LEFT (default) RIGHT CENTER JUSTIFY |
|
| VERTICAL | justify | Vertical alignment of field contents: BOTTOM (default) CENTER TOP |
|
| FONT | fontname* | Font name; in some cases this predefines the following parameters: | |
| POINTSIZE | pointsize | Point size. If unspecified, the point size defaults to the POINTSIZE defined for the form. | |
| CPI | cpi | Characters per inch | |
| LPI | lpi | Lines per inch | |
| FORMAT | formatstring* | This is a client defined input field describing how the client should format the data. This may be interpreted by the Service Provider. | |
| INITIALVALUE | value* | Initial value | |
| END |
15.2.1.5 - Media Definition
The media definition determines those characteristics that result from the combination of a particular media type together with a particular vendor's identification card or smart card. The aim is to make it easy to move forms between different vendor’s identification cards or smart cards which might have different constraints on how they handle a specific media type. It is the Service Provider's responsibility to ensure that the form definition does not specify the embossing of any fields that conflict with the media definition. An example of such a conflict might be that the form definition asks for a field to be embossed in an area that the media definition defines as a restricted area, such as on the chip of a smart card.
| XFSMEDIA | |||
|---|---|---|---|
| XFSMEDIA | medianame* | ||
| BEGIN | |||
| TYPE | type | Predefined media types are: EMBOSSCARD PRINTCARD |
|
| (required) | UNIT | base, | Base resolution unit for form definition: MM INCH ROWCOLUMN |
| x, | Horizontal base unit fraction | ||
| y | Vertical base unit fraction | ||
| (required) | SIZE | width, | Width of physical media |
| height | Height of physical media | ||
| EMBOSSAREA | x, | Embossing or Printing area relative to top left corner of physical media (default = physical size of media) | |
| y, | |||
| width, | |||
| height | |||
| RESTRICTED | x, | Restricted area relative to top left corner of physical media (default = no restricted area) | |
| y | |||
| width, | |||
| height | |||
| END |
15.3 - Command Messages
15.3.1 - CardEmbosser.GetFormList
This command is used to retrieve the list of forms available on the device.
Command Message
Completion Message
Event Messages
None15.3.2 - CardEmbosser.GetQueryForm
This command is used to retrieve details of the definition of a specified CardEmbosser form. GetQueryForm does not currently contain any form attributes, however it is retained for future expansion.
Command Message
Completion Message
Event Messages
None15.3.3 - CardEmbosser.GetMediaList
This command is used to retrieve the list of media definitions available on the device.
Command Message
Completion Message
Event Messages
None15.3.4 - CardEmbosser.GetQueryMedia
This command is used to retrieve details of the definition of a specified media.
Command Message
Completion Message
Event Messages
None15.3.5 - CardEmbosser.GetQueryField
This function is used to retrieve details on the definition of a single or all fields on a specified form.
Command Message
Completion Message
Event Messages
None15.3.6 - CardEmbosser.EmbossCard
This command is used to emboss or print an identification card by merging the supplied variable field data with the defined form and field data specified in the form. Optionally the magnetic stripe can be read and verified before being encoded, or a smart card can be updated.
The ATR of the chip must be obtained before issuing this command by issuing the CardReader class CardReader.ReadRawData command.
Clients can use UNICODE provided the Service Provider is UNICODE compliant.
Command Message
Completion Message
Event Messages
15.3.7 - CardEmbosser.Reset
Sends a service reset to the Service Provider. Any media found in the device will be captured into the specified bin (depending on hardware). The CardEmbosser.MediaDetectedEvent event will indicate that media was found in the device on reset and will indicate the position and status of the media following completion of the command.
This command is used by a client control program to cause a device to reset itself to a known good condition.
Command Message
Completion Message
Event Messages
15.3.8 - CardEmbosser.SupplyReplenish
After the supplies have been replenished, this command is used to indicate that one or more supplies have been replenished and are expected to be in a healthy state.
Hardware that cannot detect the level of a supply and reports on the supply's status using metrics (or some other means), must assume the supply has been fully replenished after this command is issued. The appropriate threshold event must be broadcast.
Hardware that can detect the level of a supply must update its status based on its sensors, generate a threshold event if appropriate, and succeed the command even if the supply has not been replenished. If it has already detected the level and reported the threshold before this command was issued, the command must succeed and no threshold event is required.
If any one of the specified supplies is not supported by a Service Provider, unsupportedData should be returned, and no replenishment actions will be taken by the Service Provider.
Command Message
Completion Message
Event Messages
15.4 - Event Messages
15.4.1 - CardEmbosser.EmbossFailureEvent
This event is used to specify that an error has occurred during processing of a CardEmbosser.EmbossCard execute command.
15.4.2 - CardEmbosser.FieldErrorEvent
This event specifies that a fatal error has occurred while processing a field.
15.4.3 - CardEmbosser.FieldWarningEvent
This event is used to specify that a non-fatal error has occurred while processing a field.
15.5 - Unsolicited Messages
15.5.1 - CardEmbosser.InputBinThresholdEvent
This event specifies that the status of the input bin has changed.
15.5.2 - CardEmbosser.OutputBinThresholdEvent
This event specifies that the status of the output bin has changed.
15.5.3 - CardEmbosser.RetainBinThresholdEvent
This event specifies that the status of the retain bin has changed.
15.5.4 - CardEmbosser.MediaRemovedEvent
This event is generated when a card is removed before completion of a write operation.
15.5.5 - CardEmbosser.MediaDetectedEvent
This event is generated when a media is detected in the device during a reset operation.
15.5.6 - CardEmbosser.TonerThresholdEvent
This user event is used to specify that the state of the toner or ink supply or the state of the ribbon reached a threshold.
16 - Biometric Interface
This chapter defines the Biometric interface functionality and messages.
16.1 - Summary
Biometrics refers to metrics related to human characteristics and biology. Biometrics authentication can be used as a form of identification and/or access control. This is an overview of biometrics, as well as an introduction to the terminology used in this document. It introduces to the concept of scanning a person’s biometric data in raw image form (raw biometric data), then processing it into a smaller more concise form that is easier to manage (biometric template data). The first scan of a user is called ENROLLMENT as the user is effectively being enrolled into a scheme by recording their biometric data. Thereafter subsequent scans of the user can be compared to the original data in order to verify who they say they are (VERIFICATION), or alternatively used to identify them as a specific individual (IDENTIFICATION).
16.2 - General Information
16.2.1 - Enrollment
The first time an individual uses a biometric device it is called Enrollment. During enrollment, biometric data from an individual is captured and stored somewhere, for example on a smart card or in a server/host database. Normally the raw biometric data captured will be processed and converted to a smaller format that is used for subsequent comparison. This format is referred to in this document as a template. A template is a synthesis of the relevant characteristics extracted from the original raw data. Elements of the biometric data that are not used in the matching algorithm are discarded in the template to reduce the file size and to protect the identity of the enrollee.
16.2.2 - Biometric Matching
During the matching phase, the obtained template is passed to a matcher which compares it to other existing templates and a probable match is calculated, either as a Boolean true or false or as a threshold indicating the likelihood of a match. With regard to matching, biometric systems commonly have two different basic modes of operation: Verification and Identification:
Verification: performs a one-to-one comparison of captured biometric data with a specific template in order to verify that an individual is the person they claim to be.
Identification: the system performs a one-to-many comparison of captured biometric data in order to establish a person’s identity.
Note: The above diagram does not make any assumptions about where the actual matching takes place. The interface provided is versatile enough to be able to support three basic Biometric systems:
Match on server: The biometric template data is stored on a server or host. When scanning takes place biometric data is sent to the server, which does the actual identification or verification.
Match on card: The biometric enrollment data for an individual is stored on a smart card/personal device. The device scans a user then returns the biometric template information to the client. This data is then sent to the card, and a client on the smart card chip does the comparison, returning the result to the client.
Match on device: The biometric enrollment data for an individual is stored on a smart card or host. The enrollment data is read from the card or host and into the device, which then compares it to scanned information, returning the result to the client.
16.2.3 - Biometric Device Types
There are many different varieties of biometric hardware, this biometrics specification supports three main different types of device:
-
Devices which only support scanning and returning biometric data
In this case the device is a simple biometric scanning device, User data is scanned using the Biometric.Read command, but matching is performed externally, for example on a smart card or on a server. In this case the Biometric.Match and Biometric.SetMatch commands are not supported. -
Devices which support a separate scan and match functionality
These devices scan and perform a comparison as separate operations. Existing biometric data is first imported using the Biometric.Import command. When the Biometric.Read command is then called the scanned user data is temporarily stored. The Biometric.Match command is then called to perform the comparison and return the result. -
Devices which support a combined scan and match functionality
These devices scan and perform a comparison as a single operation. Existing biometric data is first imported using the Biometric.Import command. In this case the Biometric.SetMatch command must be called first, either as a one time call or before each Biometric.Read command. The purpose of the Biometric.SetMatch command is to set the criteria for matching. When the Biometric.Read command is then called it scans the user’s biometric data and also performs the comparison as a single operation. The Biometric.Match command is then called to return the result of the comparison.
16.2.4 - Biometric Data Security
It is recommended that biometric data should be treated with the same strict caution as any other identifying and sensitive information. A well designed biometric data handling architecture should always be designed to protect against internal tampering, external attacks and other malicious threats. There are various ways of implementing good security of which three are listed below:
-
Multi Modal Biometrics
A Uni-Modal biometric system relies on data taken from a single source of information for authentication, for example a single fingerprint reading device. In contrast, Multi-Modal biometric systems work on the premise that it is more secure to accept information from two or more biometric inputs. As an example a user could provide a fingerprint in addition to facial recognition, a positive match from two physical characteristics improves the chances of a positive identification and mitigates the possibility that biometric data has been cloned. -
Data Encryption
Biometric data should be encrypted where possible. The Biometric specification provides for this by allowing an encryption key to be specified whenever data is exchanged between a client and a Biometric Service Provider. In addition, the key management interface methods of the PIN device class can be used for key management. This can be done by using the standard compound device mechanism to implement a Biometric Service provider as a compound device together with a PIN device class Service Provider. The device compounding mechanism is described in the API specification. In this case the Biometric Service Provider would implement the biometric methods necessary to read and return data, while the key loading, reporting etc, functions of the PIN Service Provider interface would be implemented in order to provide key management.
16.2.5 - Biometric Device Command Flows
16.2.5.1 - Biometric Enrollment Command Flow
The following table describes the flow of enrolling a user using the Biometric.Read command. Two attempts at scanning are necessary.
16.2.5.2 - Biometric Match Command Flow – Separate Scan and Match
The following table describes the flow of successfully identifying a customer whose biometric template data was previously enrolled and stored on a server/smart card/host system. This template data is first imported using the Biometric.Import command, which assigns it a unique identifying number. This identifier number can then be retrieved using the Biometric.StorageInfo command.
The Biometric.Read and Biometric.Match commands are then used to scan data and then compare it with the template identified by identifier. In this use case the device can perform a separate scan and match operation, therefore the Biometric.Read command is called to scan the subject’s biometric data then the Biometric.Match command is called to perform the match and return the result to the client.
In this case the capability matchSupported is reported as StoredMatch.
16.2.5.3 - Biometric Match Command Flow – Combined Scan and Match
The following table describes the flow of successfully identifying a customer whose biometric template data was previously enrolled and stored on a server/smart card/host system. This template data is first imported using the Biometric.Import command, which assigns it a unique identifying number. This identifier number can then be retrieved using the Biometric.GetStorageInfo command.
The Biometric.Read, Biometric.SetMatch and Biometric.Match commands are then used to scan data and compare it with the template identified by identifier. In this use case the device performs a combined scan and match operation, therefore the Biometric.SetMatch command must be used to set the criteria to be used for matching, including the imported template to be identified by identifier. When the Biometric.Read command is then called the device scans the user and performs the comparison as a combined operation. Finally the Biometric.Match command is called to return the result of the comparison to the client.
In this case the capability matchSupported is reported as CombinedMatch.
16.2.5.4 - Biometric Scan-Only Command Flow
The following table describes the flow for a simple biometric scanning device which does not support any matching at all. User data is scanned using the Biometric.Read command but matching is performed externally, for example on a smart card or on a server. In this case the capability matchSupported is reported as none.
16.3 - Command Messages
16.3.1 - Biometric.GetStorageInfo
This command is used to obtain information regarding the number and format of biometric templates that have been imported using the Biometric.Import command.
Command Message
Completion Message
Event Messages
None16.3.2 - Biometric.Read
This command enables the device for biometric scanning, then captures and optionally returns biometric data. A Biometric.PresentSubjectEvent event will be sent to notify the client when it is ready to begin scanning and a Biometric.SubjectDetectedEvent event sent for each scanning attempt. The numCaptures input parameter specifies how many captures should be attempted, unless it is zero in which case the device itself will determine this. Once this command has successfully captured biometric raw data it will complete with Success.
The Biometric.Read command has two purposes:
Scanning: The biometric data that is captured into the device can be processed into biometric template data and returned as an output parameter for enrollment or storage elsewhere, e.g. on a server or smart card.
Matching: The biometric data that is captured into the device can be used for subsequent matching. Once data has been scanned into the device it can be compared to existing biometric templates that have been imported using the Biometric.Import command in order to allow verification or identification of an individual. The Capabilities.matchsupported capability indicates if the Biometric.Match command can be used for matching, otherwise the matching must be done externally, e.g. on a server or smart card.
In either case the data that has been scanned into the device will be persistent according to the current persistence mode as reported by the dataPersistence status field.
Command Message
Completion Message
Event Messages
16.3.3 - Biometric.Import
This command imports a list of biometric template data structures into the device for later comparison with biometric data scanned using the Biometric.Read command. Normally this data is read from the chip on a customer’s card or provided by the host system. Data that has been imported is available until a Biometric.Clear command is called. If template data has been previously imported using a call to Biometric.Import, then it is overwritten. This data is not persistent across power fails.
Command Message
Completion Message
Event Messages
None16.3.4 - Biometric.Match
This command returns the result of a comparison between data that has been scanned using the Biometric.Read command and template data that has been imported using the Biometric.Import command. The comparison may be performed by this command or the Biometric.Read, this command is responsible for returning the result. Success is returned if the device has been able to successfully compare the data, however this does not necessarily mean that the data matched.
If the capability matchSupported value == CombinedMatch then the device performs a combined scan and match operation, and the Biometric.SetMatch must be called before this command in order to set the matching criteria. In this case if Biometric.SetMatch has not been called then this command will fail with SequenceError.
If the capability matchSupported == StoredMatch then the device will scan data using the Biometric.Read command and store it, then the data can be compared with imported biometric data using the Biometric.Match command.
This command can be used in two modes of operation: Verification or Identification, as indicated by the compareMode input parameter. The two modes of operation are described below:
Verification (compareMode == verify) :
In this case a one to one comparison is performed and the maximum input parameter is ignored. The data that has been scanned previously using the Biometric.Read command is compared with a single template that has been imported using the Biometric.Import command. If there is a successful match then the ConfidenceLevel output parameter can be used to determine the quality of the match and will be in the range 0 – 100, where 100 represents an exact match and 0 represents no match.
Identification (compareMode == identify) :
In this case a one to many comparison is performed. The data that has been scanned previously using the Biometric.Read command is compared with multiple templates that have been imported using the Biometric.Import command. The input parameter maximum is used to specify the maximum number of matches to return: a smaller number can make execution faster. The required degree of matching similarity can be controlled using the threshold parameter which is used to control the frequency of false positive and false negative matching errors. The value of threshold represents the criteria as to what constitutes a successful match and is in the range 0 – 100, where 100 represents an exact match and 0 represents no match. If for example, threshold is set to 75 then only results with a matching score equal to or greater than 75 are returned. The matching candidate list is returned in the matchResult output parameter sorted in order of highest score. The higher the value of confidenceLevel the closer the candidate is to the beginning of the list, with the best match being the first candidate in the list. Note that where the number of templates that match the criteria of the threshold are greater than maximum, only the maximum templates with the highest score will be returned.
Command Message
Completion Message
Event Messages
16.3.5 - Biometric.SetMatch
This command is used for devices which need to know the match criteria data for the Biometric.Match command before any biometric scanning is performed by the Biometric.Read command. Biometric.Read and Biometric.Match should be called after this command. For all other devices Unsupp_Commmand will be returned here.
If the capability matchSupported == CombinedMatch then this command is mandatory. If it is not called first, the Biometric.Match command will fail with the generic error SequenceError. The data set using this command is not persistent across power failures.
Command Message
Completion Message
Event Messages
None16.3.6 - Biometric.Clear
This command can be used to clear stored data. In the case where there is no stored data to clear this command completes with Success.
Command Message
Completion Message
Event Messages
16.3.7 - Biometric.Reset
This command is used by the client to perform a hardware reset which will attempt to return the biometric device to a known good state.
Command Message
Completion Message
Event Messages
16.3.8 - Biometric.SetDataPersistance
This command is used to set the persistence mode. This controls how the biometric data is persisted after a Biometric.Read command. The data can be persisted for use by subsequent commands, or it can be automatically cleared.
Command Message
Completion Message
Event Messages
None16.4 - Unsolicited Messages
16.4.1 - Biometric.PresentSubjectEvent
This execute event is generated to notify the client when the device is ready for a user to present the subject to be captured to the biometric scanner, for example, placing a finger on a fingerprint reader.
16.4.2 - Biometric.SubjectDetectedEvent
This execute event is generated to notify the client when the device has detected a subject in the capture area and an attempt to capture biometric data has been performed.
16.4.3 - Biometric.RemoveSubjectEvent
This execute event is used to notify a client that the subject should be removed from the capture area of the device.
16.4.4 - Biometric.SubjectRemovedEvent
This service event is generated when the subject has been removed from the capture area of the device. This event may be generated at any time.
16.4.5 - Biometric.DataClearedEvent
This mandatory event notifies the client when data has been cleared. This can be the case when the data is cleared automatically after a Biometric.Read or Biometric.Match command completion, or as a result of an explicit call to the Biometric.Clear or Biometric.Reset commands.
16.4.6 - Biometric.OrientationEvent
This event is generated when the biometric subject has an incorrect orientation relative to the device scanner in order to allow a client to prompt a user to correct it.